Comments

[PlainName]

So have a go at Karel too, then. Or are you scared you might upset him?

But, better, see Dave's take on it.

[xrunner]

Where did he say it's a good idea to leave the member's name and link back to the post off of a quote?

See what you wrote here -

Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

Tree and forest problem.

That's just a ridiculous and poor quoting habit. You need to lose that one. 

[PlainName]

None so blind...

You are deflecting. It was about full quotes, not attribution.

[xrunner]

None so blind...

You are deflecting. It was about full quotes, not attribution.

It can be about anything I want it to be about at any time I wish. You seem to not like your bad habits being pointed out it seems. 

[tggzzz]

Why does no-one write comments any more? ...

Probably because they hung around a guy I used to have to associate with at work. He worked in another dept. and wrote some C software for a project we were trying to get to operate correctly. I was looking at the code and it was simply undecipherable in the whole. I asked him to explain it to us because there were no comments at all. He said he didn't need to because it was "self-documenting". Anyone who understood C should be able to follow it and understand. If you can't do that then you don't understand programming and shouldn't be trying to help.

 

That's the modern religion. It has a little validity in that, presuming the code is tasteful and literate, there is a good chance the comment will become out of sync with the code.

It completely ignores the concept that, even with tasteful and literate code, a comment should indicate "why" and "contextual use".

[ataradov]

I don't write comments because I personally don't like reading them. The first thing I do when trying to understand unfamiliar code is strip the comments and see what the code does. This does not apply to the API documentation, of course.

At the same time I just write readable code and my expectation is, if you can't read it, you probably would not be able to use it anyway.

[xrunner]

It completely ignores the concept that, even with tasteful and literate code, a comment should indicate "why" and "contextual use".

Well if it is written

x = a + (b / c);

of course any person can read and understand what that does - what is the calculation mathematically. What it doesn't tell us is why does the program need to get a value for x from those variables? What is being accomplished?

What this guy thought was you can understand what the program does by reading these lines one by one and understanding what the program is accomplishing with no comments at all. Of course given enough time you could ... but who has all that time for a very complicated program?

[ataradov]

Very complicated program would have a lot of comments in that case. And realistically it is better to read the code rather than novels about the code.

And you should be able to understand what the code does from the function name. If you have a huge wall of text function, then again, it is more of a programming style issue rather than comment issue.

It is fine if the comment says something like "calculate offset of the button on the screen". But if it goes into describing every single detail about that calculation, it would be a drag to read.

[alm]

x = a + (b / c);

Unless a, b and c were variables that made sense in some specific domain, I'd say this is bad code. How about:

Code: [Select]

int calculate_x_offset(int margin, int text_length, int character_width) {
  return margin + (text_length / character_width);
}
Would you still need a comment?

What this guy thought was you can understand what the program does by reading these lines one by one and understanding what the program is accomplishing with no comments at all. Of course given enough time you could ... but who has all that time for a very complicated program?

At the top is a function like draw_graph(). This already tells you a graph is being drawn. Then this function will call other functions to draw axes, the points, labels, etc. To get a gist of it, just look at the top level functions. Let's say it reads like this:

Code: [Select]

function draw_gui() {
  draw_sidebar();
  draw_graph();
  draw_console();
}

So by just reading this, I learned that the code is drawing a GUI consisting of a sidebar, graph and console. You probably don't have to look at how text is being rendered or how an UART is initialized to understand what a program is doing. Since functions should be organized from high level to low level, just stop reading whenever you have reached the level of detail that you needed to know.

[xrunner]

Yes alm that is very bad code because the variables are not explanatory. But that is just about as bad as some complicated software I've seen written for the area I worked in, i.e. not for sale outside the company. If the variables are well named of course it helps understanding what the lines of code are for, what they are calculating to achieve a desired outcome in the control of equipment or the screen display of data for the user.

[ataradov]

Ok, but then we should not say "let's write good comments", but simply "let's write good code". Why write bad code and then good comments to explain that bad code?

And people that write bad code, won't be any better at writing comments anyway.

[Siwastaja]

Good commenting has always been scarce. Even "known good" code is often commented like this:
i++; // i is increased by 1
while it lacks real comments, like large pieces of text which explains how the interface is used, and why the module is designed like it is.

Probably programmers are irrationally afraid of writing large comments because someone has told them, in the past, that this should be a "separate documentation". Fair enough, but if they don't write that "separate documentation" while writing the code, they will never come back to write it, and no one else will do it either. Therefore it is safest to write every piece of documentation that comes into mind as code comments. You can always later refactor them into a separate document if the line count seems to explode, you start needing images and ASCII art does not cut it...

Commenting single lines all over the code base indicates some fundamental problems:
* Hopefully just tendency to write unnecessary comments. Harmful, but they can be ignored
* Tendency to write code which is so messy it needs such comments
* Inability to do good naming. Why write:
  float a; // this is acceleration
  when you can write
  float acceleration;

I have been shocked to see how poorly the interfaces of some widely used libraries are documented. It seems all the effort goes into satisfying the Doxygen syntax, and then the actual content is missing. "Oh, we listed the parameters and the autogenerated html looks professional, job done". Fuck these guys. As a C programmer, I absolutely need to know if the function makes copy of the data pointed by ptr, or if I, the caller, need to keep the buffer allocated. If this information is missing, then the library is unusable, documentation is completely broken. And it often is.

[tggzzz]

Very complicated program would have a lot of comments in that case. And realistically it is better to read the code rather than novels about the code.

And you should be able to understand what the code does from the function name. If you have a huge wall of text function, then again, it is more of a programming style issue rather than comment issue.

It is fine if the comment says something like "calculate offset of the button on the screen". But if it goes into describing every single detail about that calculation, it would be a drag to read.

Oh, you lucky person. Now you can have more fun in your life by reading https://thedailywtf.com/series/code-sod

The front page contains links to classic articles.

Personally I use the RSS feed.

[tggzzz]

Ok, but then we should not say "let's write good comments", but simply "let's write good code". Why write bad code and then good comments to explain that bad code?

And people that write bad code, won't be any better at writing comments anyway.

Occasionally it is beneficial to write a comment to explain why apparently bad code is actually appropriate.

The existence of bad programmers writing bad comments does not make comments bad. After all, while "all crows are black birds" it does not follow that "all black birds are crows".

[bpiphany]

Snapshots from above video. Write good documentation, not comments. (And good code of course.)

[magic]

How about:

Code: [Select]

int calculate_x_offset(int margin, int text_length, int character_width) {
  return margin + (text_length / character_width);
}
Would you still need a comment?

I still have no idea what margin is, why would you add to it what appears to be the number of characters in text, and what the resulting offset is supposed to be.

edit
Actually, wtf, text_length is not text_width, so is it character count? What would be the point of dividing that by character width?

And this is a perfect example why you guys are insane. Your code is clearly buggy, and without comments I have no idea how to fix it.
Is it supposed to be multiplication and the resulting offset in pixels? Perhaps inches or millimeters?
Is it supposed to be text_width, with margin and the result in units of characters?
Something else that hasn't occured to me yet but will, if I spend an hour trying different things and inspecting all call sites?
(In reality: the function is undocumented, so different call sites assumed different things, it's all FUBARed and only "worked" by luck and insufficient testing).

Pro tip: If I'm reading your code, it often is because either the code or something connected with it is screwed up. I probably already know what the code is doing before reading it because I see the effects, so thank you very much. What I don't know is what it was supposed to do differently, and in which place.


Or how about this example I just wrote:

Code: [Select]

#define MEG 0x100000

// read buffer, must be page aligned, MEG is safe overkill
#define BUF (16*MEG)
__attribute__(( __aligned__ (MEG)))
char buf[BUF];
versus equivalent self-descriptive code

Code: [Select]

#define MEG 0x100000
#define BUF (16*MEG)
__attribute__(( __aligned__ (MEG)))
char sixteenMBbuffer_page_aligned_actually_MEG_aligned_becasue_Im_lazy[BUF];

[PlainName]

The first thing I do when trying to understand unfamiliar code is strip the comments and see what the code does.

That's an interesting approach (and pity the reverse can't be done!) . Do you just do that when you are working on the code, or if you're just browsing to get an overview too?

[PlainName]

Ok, but then we should not say "let's write good comments", but simply "let's write good code". Why write bad code and then good comments to explain that bad code?

And people that write bad code, won't be any better at writing comments anyway.

What is 'good code'? In the sense of being able to understand it, I mean. We go on about suitable names for functions and things, but thinking up those names can be really difficult. I know I have trouble achieving that on the fly. And the problem is that even fantastic names don't tell us why, only what.

[PlainName]

It seems all the effort goes into satisfying the Doxygen syntax, and then the actual content is missing.

Yep, more than once I've had my hopes raised by great-looking documentation actually existing, only to find it's completely useless doxygen output. And typically they also leave out the call tree diagrams too.

[Karel]

IMO, assuming the software comes for free (free as in speech, not as in beer), choose one of the following options:

• Pay somebody (ideally the original programmer) to write/improve the comments.
• Write/improve the comments yourself
• Use the software and accept the bad comments.
• Do not use that software.

Things that we should not do IMO:

• Whining about it
• Shaming the programmer

 

[Nominal Animal]

All of the above is why I tell learners to focus on writing comments that describe their intent, instead of describing the code.



When I implement a standard Xorshift64* pseudo-random number generator, I simply name it.  When I only use the 32 to 40 high bits of its output, I mention that that way the output passes the full BigCrunch randomness tests, and is thus "better" than e.g. Mersenne Twister (MT19937).

In multithreaded code, I use comments to describe the locking schemes.  For standard pthread_mutex_t protecting a set of variables, I mention that where the variables are declared, but for anything more complicated, I mention the scheme is described in an external document (LOCKING, typically).

If I implement an easily rehashed hash table or say a disjoint set data structure, I describe it as such, and try to explain why it was chosen (by describing the most important features, and most unimportant downsides).  There is no need to explain standard abstract data structures internals; only if one deviates from standard data structures.  For example, if you create a thread-safe binary tree, you definitely need to describe the locking scheme and its limitations, especially wrt. node deletions and concurrent traversal.

For embedded/microcontroller code accessing hardware, it is nice to have a root-level block comment describing where that hardware is documented, especially when multiple subsystems are used.  (Say, an interrupt and DMA-driven SPI interface, and its latency and interrupt priority requirements.)

There is absolutely no way to reliably infer developer intent from the code itself.  The code is the result, not the design; and any particular feature –– or even the overall approach –– may be an unintended error, or more commonly, a misunderstanding or a "thinko": a logic bug/error similar to a typo.  These happen to every single human programmer.

When dealing with code without comments describing the developer intent, I always have to try and infer that first.  It is a heuristic process, and therefore prone to errors.  Anyone claiming they don't write comments because they don't think they are necessary, needs to be hit with a cluebat.  The true purpose of comments is to provide the information the code does not provide, and that is intent.  Only when the intent is known, can one compare the implementation to the intent.  Even then, either one can be faulty!  When the intent is not documented at all, it can only be inferred from the code, which takes time and adds another possible source of errors.

When I am trying to fix or extend others' code, my most common thought is "what the hell did the author of this crap think when they wrote this?"
because in a vast majority of cases, problematic code could be simplified by switching to a better algorithm/approach.  This definitely applies to my own code as well, because "good code" is not simply written once and then put out there.  Truly good code evolves through refactoring and algorithmic optimization.  Sure, if you intend to write a piece once and never touch it again, you can omit any comments and write documentation that satisfies the client, but such code is never, ever truly "good"; not when compared to code that has been refactored and competed with other possible implementations.

This is why documenting the developer intent matters: it provides the information needed to fix/enhance/refactor the code in the longer term, allowing it to evolve instead of just accumulate/aggregate into a larger, more complex whole.  If your refactoring increases rather than decreases the complexity of the whole, you are doing it wrong.  Having to try and heuristically infer the developer intent from the code is unnecessary waste of effort, because the intent can always be described in simple, short comments.  Not even trying to write them in the first place is, well, kicking extra work onto others because you're too lazy to do your own bit.

[madires]

Some very simple code:

Code: [Select]

  TCNT1 = 0;
  TCCR1A = (1 << WGM10) | (1 << COM1B1);
  TCCR1B = (1 << WGM13);

If you know that MCU's registers well you might be able to tell what is done here. Otherwise you would have to spend some time reading the datasheet.

Now with comments:

Code: [Select]

  /*
   *  set up Timer1 for PWM
   *  - phase and frequency correct PWM
   *  - top value by OCR1A
   *  - OC1B non-inverted output
   */

  TCNT1 = 0;                            /* set counter to 0 */

  /* enable OC1B pin and set timer mode */
  TCCR1A = (1 << WGM10) | (1 << COM1B1);
  TCCR1B = (1 << WGM13);

Some lines further down OCR1A is set and the timer enabled (by setting the prescaler).

[PlainName]

Just noticed an excellent example:

https://www.eevblog.com/forum/kicad/handcrafted-footprints-for-kicad

OK, it's not C but if you are hip to the language (and who wouldn't be if you're using Kicad) the comments still make a LOT more sense than the raw code without. Hell, even I could see what the thing does with just a couple of seconds of speed reading, and I use Altium!

[Siwastaja]

Snapshots from above video. Write good documentation, not comments. (And good code of course.)

The problem with this mindset is that unless you make it 110% absolute sure that the separate documentation is
A) written in the first place,
B) maintained,
C) easily available, easy to find, easy to access, easy to read,

this just reduces into not having the documentation at all since "I can't put it in comments".

If you document interface functions properly in the .h file (for example), then I can, in an IDE or code editor, see this documentation automagically as I write code. I have never seen an interface function being documented too well. The opposite problem, too little, is usual. Once properly documented in code comments, automated tools such as doxygen can be used to create the separate documentation for those who prefer to have it, so it's a win-win.

And it's no only about interfaces. If I want to look at why the implementation is like it is, of course I would be looking at the code anyway. Once I have the code file open, why not have documentation there? Of course this isn't a substitute for project-wide documentation which for example explains how the modules interact.

[SiliconWizard]

All of the above is why I tell learners to focus on writing comments that describe their intent, instead of describing the code.

Yes.