0

When commenting code, which of the two approaches considered good practice?

  1. Explain the content of the code, "translate" it to human - readable language, but not provide any explanation regarding why the code was written the way it is, why this and that part are necessary, etc..
  2. Explain the content of the code, as well as providing Explanations such as: why I use X and not Y, what design pattern do I follow when I do this, How can this part be used, etc.. (as well as what I mentioned above)

example of approach #1:

/*calling some_funct to do X and checking whether there have been any error*/
if(some_funct())...

example of approach #2:

/*calling some_funct to do X and checking whether there have been any error.
Errors returned from the function are not printed to the user
because the function prints its errors to the user from within itself*/
if(some_funct())...

So which one should I use? I believe the first approach to be more minimal and sometimes easier to read, while the second one seems more easier to understand.

In most of the docs I have seen right now the "no motivation" approach is more commonly taken, but this can be attributed to the fact I mostly use comments explaining the function itself and not the in - code comments which has more of an incentive to reason the code behavior.

avivgood2
  • 117

2 Answers2

3

In the comments, you should tell what is not in the code.

Therefore, I recommend option 3:

  • only comment motivation of a code block, and definitions: Code may be updated, but the motivation generally remains unchanged. Exceptionally, and only if the code is wicked or uses some far-fetched tricks should you explain what it’s doing.

If you comment the definitions of your function, any decent IDE will provide it to the reader: no need to repeat this definition in the comments everywhere you call that function. If btw you’d chose good function names, the code could become self-explanatory with even less comments.

Dummy naive example:

// Connect to remote web service
auto url = fetch_in_config(“ws-repository”);
auto error = connect_to_server(url, ...);
if (error) {
    ...
 }
 // no need to comment more!

Other dummy example:

// determine connection id
unsigned long key = get_account_key ();
key = (key<<1) & 0xeeeeeeee; // shift every hex digit by 1 without overflow
key++; 
....

Of course my recommendation is a general guidance. In reality there can be a couple more valid reasons to comment. Mere info:

Christophe
  • 74,672
  • 10
  • 115
  • 187
1

One thing that I've found helpful is to be practical about comments and about how descriptive the comments and code are. I usually ask myself some of these questions:

  1. Who am I writing the comment for? Is it for just me, or for someone that may have to maintain this code in the future?
  2. What insight would a fresh set of eyes glean from this comment? Is it a fairly timeless comment (e.g. gravity will always exist even in the future), or a timely comment (refactored this for better understandability. If it is the first, maybe put that comment in the code. If it is an implementation detail, perhaps make a comment in the git commit message, or a design doc if you do that sort of thing. This way the comment is where it needs to be (in the code for the duration, or at a point in time in a git commit message).

Remember also, and I'm not trying to be a wise-guy, but

  • Comments don't compile
  • A comment that may be true today may not be true tomorrow if the code changes

Keeping those things in mind may change the perspective in which one writes/values comments. It may help prevent you from misleading yourself or others when you need to get through the code quickly.

cowboydan
  • 221
  • 1
  • 4