The art of commenting code

It’s simple, I’m reading some old C code right now (but it’s a general thought really) and it lacks comments so I’m trying to understand what it does for using it proficiently, I know that I’m not a “comment guy” cause I only now and then put comments in my source code, but managing a medium C++ project in the last few months (my bachelor thesis) I’ve finally understood what to comment and what not.

First of all I don’t like commenting every line of code, it’s stupid and it’s wrong, good code must be readable also without comments, comments are for helping readers to understand the “whole thing”, so they must refer to widen pieces of code, pieces that you can understand also without the comments but that with them become more easily to be understood by you.

So I’ve started to comment the critical point of my code, the decisions taken and the rationale beside them and I’ve found, finally, what I absolutely need to comment: data structures.

The rationale it’s simple, if algorithms have a behavior that you can follow to understand them, data structures haven’t, you can’t understand them if they want, or better, you can but you have to spent lot of time trying to find every use of them and it’s not cool, absolutely isn’t 😉

So, I started to comment my data structures, their fields, how they must be used and the meaning of them, why don’t you ?

(This is all because the code I’m reading right now has no comments and some strange graph data structures with fields not understandable if you are not the author, and I’m not)