How to properly comment your code

I feel like that's the kind of comment you write when you've spent way too long working something out 🤔 or maybe that's just me 😂

@Elyz I wrote it while I was thinking it out :)

That's documentation not a comment. Would be better if it was in a proper documentation file with an algorithm diagram referencing the code.

@rutee07 Seconded. That's a pissed off dev.

@rutee07 @root

That's my code, and the only reason it's so... well explained... is honestly because I had trouble with the algo the first time around so I took a step back and wrote it all out and after I finished I was like damn... this is some quality commenting.

@rutee07 No, it's my thought process put into characters in a code editor

These comments are appropriate... If it's an example code for high school students. :)

No offense but you can get rid of 90% of comments with proper variable, function and type naming.

Should render? Make it a function or boolean called like that etc.

@3psilon This is code within a member function called shouldRender, which I am renaming to clipCheck soon

Every time the topic of commenting comes up, I'm always scared to death when I see that ~75% of the replies basically boil down to "commenting is bad, don't bother". I can only assume most developers who bother to post a comment to something like this are new-to-the-field juniors who haven't had to maintain mission-critical, poorly commented legacy code, or who haven't had to revisit THEIR OWN CODE years later and so don't know any better yet. At least, I always sincerely HOPE that's the case because if not... FFFFFUUUUUUUUUUCCCKKKK.

Working with qt?

@Nicci Nah it's my own GUI system

I normally don't write comments like that. Just if it is something that had me confused or was a bug that remained in the code base for a long time.
So if you struggled with the code yourself I think a comment like this is the right thing to do.

Writing very explicit comments also adds to maintenance. What happens a few years down the line when people have updated the code but forgotten to change the comments? Then your comments are out of sync with you code.

Design on an "interface level", i.e. what does people using this function need to know? They probably don't need to know the inner workings of the function, only how it is expected to work from an outside perspective. That's what your documentation/comments should convey.

Wasting time on documentation...
We <3 legacy code!!!

templeos - for all of the weirdness that it is - has a really cool feature where you can embed full images, flow charts etc in to comments in source code

Nice! I prefer comments like that over putting a link to some diagram, document or whatever, because such a link may not exist anymore when you need it.

I too use extensive comments for things that really need explanation. Recently I worked on some UI compents that had a lot of complexity in regard to show/hide things, show them enabled/disabled etc. all based on several logical conditions. I used formal logic to work this all out and now it works perfect! I added the whole logic approach as comments so that in the future it is clear why it is done like that and also provides the logic formulas so you can easily change or extend if needed without lots of efforts in figuring it out all again.

those comments are very clear. 😊
I personally prefer to see comments about code to be above the code it's for, instead of all the way at the top of the file. Both easier to read and edit. ^^

@irene Certainly it CAN mean that, but it doesn't have to, not even most of the time. Naturally though, it depends on the quality of the comments. If they fill in the gaps that the code itself can't provide - the rationality behind the code - then that doesn't mean the code is in any way unclear or poor. It's just the realization that code tells you the what, but it doesn't tell you the why. It doesn't tell you all the thinking that went into the code, and that's the kind of information that is of vital important when trying to maintain code, especially very important code.

The more likely to be found comment:

// This works, if you can't understand why don't touch it.

I'm currently reading a book called "Clean Code" (which I may recommend btw) - And the author basically says you shall always write your code so well, that you need no comments. This is like a very bad opposite example.

@DeWil Arithmetic is written well and self-explanatory, but I still need explanation every time I see a complex formula. Same applies to code. No-comment coding is a disease of laziness. But I agree with the moral of the book. I just think 0 comments is wrong and impossible.

@AlgoRythm I think it depends, in the book are some examples where Comments are good and needed, but only a few. Comments can get outdated very quickly and the amount of work put into them would probably better spent refactoring the code. But I agree. I'm just saying you should have a different approach ^^

@DeWil I knew that if I came back to this code (which will not likely be changing) and tried to understand it, it is likely that I would get confused. I wrote myself an essay. It's atypical of me to write this much. But I needed the though

@AlgoRythm I understand your thinking but I still don't agree. You could still refactor a lot of that code, rendering the comment useless. But it's okay to do it your way, I may still recommend that book to you, 'cause learning is always good ^^

@3psilon THIS

This habit would save a lot of time for understanding process

@kwilliams yeah, and generally, I get mad because it doesn't work, mainly because of an edge case that the OP didn't understand.

work of art

@fzammetti 90% of the comments I read are out of date and inaccurate, *especially* in "legacy" codebases. A comment is failure to clearly express thoughts in code. In my opinion, it's better to simplify code so reading it is just as easy. The ability to clearly express thoughts in code is *much* more important than comments. If functions are longer than 4 to 8 lines, no amount of comments is going to stop the codebase from becoming a cluster fudge of burnt spaghetti. Just a matter of time and it becomes the "legacy" codebase. This is my experience.

@ymas Comments being out of date and inaccurate are a failure on the part of developers and should be treated as such just as unsquashed bugs are. This only happens when developers have the mindset that comments aren't as important as code and that's what has to change. I do agree however that being able to express thoughts in code IS more important, but they aren't mutually exclusive things because no matter how clearly you express your thoughts in code, there is almost always sure to be something missing that code alone simply CAN'T express (the reasoning behind why it is the way it is and how it fits into the bigger picture to name two). My experience tells me that when you have professional developers with the proper minset and dilligence you wind up getting BOTH clearly and well-written code AND accurate and current comments that make understanding a system holisitcally MUCH easier than either alone ever could have.

Keep up the good work , I read few posts on this web site and I conceive that your blog is very interesting and has sets of fantastic information.

@Kage good

Writes a fantastic comment... but then goes and cancels it out by using eight spaces for indentation while not putting a space between if and the opening parenthesis or between the closing parenthesis and opening brace?!

What a monster! Get him!