Description of a function statement

1

I have a question in making descriptive comment related to the parameters of these 3 functions below.

int proximoClientePreferencial(CLIENTE *filaPreferencial){
void mostrarFilaPreferencial(CLIENTE *filaPreferencial){
void adicionarFilaPreferencial(CLIENTE *filaPreferencial, int 
 tempoUtilizando){

Agree to such comments:

// inteiro representando filaPreferencial    
int proximoClientePreferencial(CLIENTE *filaPreferencial){

// ponteiro de um nó filaPreferencial
void mostrarFilaPreferencial(CLIENTE *filaPreferencial){

// ponteiro de um nó filaPreferencial
// inteiro representando o tempo de atendimento em uma Fila Preferencial
void adicionarFilaPreferencial(CLIENTE *filaPreferencial, int 
 tempoUtilizando){
    
asked by anonymous 02.06.2017 / 16:17

2 answers

-2

Friend do as you wish in your comments, when commenting some code I always try to be as objective as possible, as I have already said here, to be explicit for anyone to understand. Because in the future someone can maintain your code, so try to be as clear as possible, commenting everything, about the names of the functions I believe is correct, it is clear, at least that is my view of your doubt. Hope this helps. Anything is just calling.

    
02.06.2017 / 19:44
2

A little history

I decided to answer because there is a vision created in the 50s / 60s that should comment code. It was very necessary because they programmed in Assembly that can not be clear in the code or also languages that had limitations the amount of characters of the identifiers or even when there would be some type of cost in some phase of the development or execution in having larger identifiers. >

As languages have evolved and computers have passed capacity that does not make it difficult to have more meaningful identifiers, in addition to three tools that help you write code but are readable effortlessly, the comments are no longer useful as well.

Because comment is helpful

They are still useful to indicate why something non-intuitive was done that way. Comments that say what the code is doing does not make sense anymore.

It turns out that many people who became teachers learned programming at that time that made sense, and did not realize the paradigm shift in coding. They kept repeating the mantra of commenting everything.

This shows that even in the past people already liked to learn by recipe of cake, by good practice, which are nothing more than rules that people follow blindly without because they are doing it. It looks like Mandinga, superstition.

Engineer should only do something when they are because they are doing that.

These teachers have trained professionals and other teachers with the same idea of commenting everything and following golden rules without knowing the foundation of that. And today almost everyone who learns a little to program themselves considers themselves to be informal teachers and can teach others, even if they themselves do not know well about it. Did you realize how you saw a cordless phone? There was a real motivation for the comments at all, today the motivation is different, but people still adopt what they have heard without question.

Comments are bad

If the code is well written in the future it will be easy to maintain without comment. If the reviews exist in excess either they are redundant or they are fixing a code readability defect. Fix the right defect.

And being redundant is bad, it hurts DRY , it creates maintenance problems since if the person chose to give the readability of the comment instead of the code will hardly always keep the code and the comment synchronized. Anything that requires synchronization calls for trouble in the future and create even greater readability issues.

Your code

It is well readable. Maybe I can improve it a bit more, but I do not see the need for comment, and if so, then improve the code. To put comment in this case is to fix the wrong defect, if it is defective. It's gambiarra, it's following cake recipe for zero benefit.

Some people will say that it even has redundancy in the code itself, but in C I think it's normal, it does not have better mechanisms to solve certain ambiguities. Congratulations on the code, my condolences for thinking you need comments. I hope it evolves at this point, it is above average.

Conclusion

I'm not a dissonant voice in the developer community:

03.06.2017 / 19:44