Description of a declaration by reference

Asked

Viewed 127 times

0

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 with 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){
c comments

  • Friend do as you wish in your comments, when I comment on some code I always try to be as objective as possible, as already said here, be explicit to anyone 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 this is my view about your doubt. I hope I helped. Anything just call.

1 answer

5

A bit of history

I decided to answer because there is a vision created in the 50/60 years that should comment code. It was very necessary because they programmed in Assembly that has no way to be clear in the code, or even in languages that had limitations in the number of characters of the identifiers, or even when there would be some kind of cost at some stage of development or execution in having larger identifiers.

As languages have evolved and computers have become capable of having more meaningful identifiers, as well as having tools that help write code but readable effortlessly, comments are no longer as useful as.

Why comment is useful

They are still useful to indicate because something not intuitive and was made that way. Comments that say what the code is doing no longer makes sense.

It turns out that many people who became teachers learned to program at that time that made sense, and didn’t notice the paradigm shift in coding. They kept repeating the mantra of commenting on everything.

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

Engineer should only do something when they know why they’re doing it.

These teachers formed professionals and other teachers with the same idea of commenting on everything and following golden rules without knowing the basis of it. And today almost everyone who learns a little programming considers themselves informal teachers and can teach other people, even if they themselves don’t know much about it. Notice how you turn into a cordless phone? There was a real motivation for the comments in everything, today the motivation is different, but people still adopt what they heard without questioning.

Comments are bad

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

And being redundant is bad, hurts the DRY, creates maintenance problems since if the person preferred to give readability by the comment instead of the code it will hardly always keep the code and the comment synchronized. Anything that requires synchronization asks to give problem in the future and create even bigger problems of readability.

Your code

It is very readable. Maybe you can improve a little more, but I do not see the need for comment, and if you have, then improve the code. Put comment in this case is to fix the wrong defect, if it has defect. It is gambiarra, is to follow cake recipe for zero benefit.

Some people will say that there is even redundancy in the code itself, but in C I think it is 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, otherwise it is above average.

Completion

I’m not the voice of dissent in the developer community:

Browser other questions tagged c comments

You are not signed in. Login or sign up in order to post.