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

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. ^^

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.

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