Ranter
Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
Comments
-
LlamaMan8695yI follow what Uncle Bob said and try to write my code for humans, and not for the computer (self explanitory code)
-
Asbetha6725yThe best comments are the ones that not need to be written.
The best documentation is your code. Write code like a story.
If you are programming some bad ass math calculation, comment everything ONLY if the others are going to read the code and have no such depth inside like you in the topic -
Asbetha6725yI had to refactor some code and it drove me nuts.
Old comments that do not match with what the code is doing.
Or comments on methods like
// returns the backgroundcolor
public Color getBackgroundcolor()
but on Behemoth methods that have 3k lines of motherfucking code -> 0 comments!!!!!! -
@halfflat @Asbetha @LlamaMan problem is long term maintenance. I can understand and write clean code now but will I understand what the fuck is going on 9 months later? I doubt it. So i comment even a dumb piece of code that is obvious what it does. Better to comment every line now while i have fresh memory of its usage than to guess what it does 9 months later, right?
-
Asbetha6725yYou should write an SDD and a doc with dev notes.
Face it. You will read your code anyway again to understand everything. Instead of thinking, how can I remember why I thought like that, save the ideas how everything is structured and connected. Also write some notes if there are some hacks implemented because of some possible error that occurs in specific use cases -
Voxera113885y@SukMikeHok instead of massive amounts of comments, use good variable names, and break up one liners into multiple lines and variables for intermediate values, that often helps and gives an automatic in code documentation.
Extract code into descriptive methods.
And if required, add method comments instead of code comments, they are less likely to be separated from the method they belong to and often are visible in intellisence.
Most of the time I find I rarely need comments in code.
And if I still do, I try to place it at the end of the line to avoid the risk of other code slipping in between. -
KiDoDa1255yHere's a good test: when you wake up first thing in the morning before coffee even, pull up some code you wrote a week ago, if when skimming through you say: "WTF", you need more comments.
-
RUSerious155yReal programmers don‘t comment their code. If it was hard to write, it should be hard to read.
-
I'd say only add comments if it really explains something and adds true value. In general, applying proper conventions like naming etc. will lead to readable, understandable code without need for comments. If you plan to reuse some library you develop, be sure to add comments to all public api members. If you write a piece of code that is not very easy to understand or you did things in a certain way for a particular reason, then a comment can be helpful. E.g. you write a method to fetch some data from multiple sources and convert that into something else, you could add a comment when 1 of the statements needs to be executed first in order for the next statement to succeed. You should avoid such coupling but in cases like this adding a comment will be helpful.
-
retnikt67745yI sometimes wish you could put LaTeX into comments to explain formulae in complex algorithms (or even just basic physics/maths). Other than that I tend to let the code comment itself, with a broad overview at the top of each block where appropriate. But when I used to write code at school, every line would be meticulously explained with, quite often, a 2:1 ratio of comments to code.
Is it better if my code has 0 comments or 9999999999999 comments as in, literally commenting every single line of code, explaining exactly what the variable is used for, method etc?
rant