3 ms·
I should also point out that comments are a code smell. The vast majority of the time you feel the need to add a comment, you should probably refactor your code
by EGreg 3y ago
I should also point out that comments are a code smell. The vast majority of the time you feel the need to add a comment, you should probably refactor your code into a well-named function — whether a closure or a method. Your code should read well even without comments!
(There are some exceptions, that have to do with notes eg for security implications, or optimization techniques, or side effects. And also to document parameters in duck-typed languages. But even those should be put into structured comments, like DocBlock or YUIdoc or whatever kids use these days.)
I have learned this with time. Like when you are procrastinating and putting off doing something, that’s a sign you need to attract partners.
- bartwr 3y agoWhat a terrible advice (sorry). Great comments are not about "what does this code do?". They are about "why does it do it?". In some domains like scientific or high performance computing they are absolutely necessary to a) provide context to others b) make you not forget c) prevent unintended consequences and regressions. You reorder some operations or do seemingly weird things for improved performance, numerical stability, or address some not easily testable bug? If you don't comment it, this knowledge will be lost and someone might obliterate it during a refactor.
- gonzo41 3y ago---I should also point out that comments are a code smell. I would encourage you to ponder this a little more. I work on scientific code bases and there's just some processes and math that requires line by line exposition beyond what the code can offer. There's also nothing worse than digging into a library to view the code and just being left with a ton of small classes and no notes on how it's all meant to interact. Comments here and there are helpful.
- garethrowlands 3y agoThe book the post mentions, A philosophy of Software Design, has a lot to say about having lots of small classes. It’s not in favour. That book is also strongly in favour of comments, lots of them. This book is well worth reading.
- EGreg 3y agoInstead of here and there, why not write a manual that ties it all together? As you said, “a ton of small classes” might not be enhanced so much by “a ton of small comments”
- sfn42 3y agoI started out writing Java. I have seen a lot of people complaining about the java docs, but to me they are the best docs I've ever used. Python isn't even close, JS is just a bad language in general, C# docs are pretty good but I still prefer the java docs even though I use C# professionally. My point is, the java docs are just comments. It's a html page (or you can explore it directly from an IDE) generated from the code and its comments, it describes the code and how to use it. Almost anything I want to achieve I can achieve by exploring the java docs. The type system itself tells me which things fit together and if anything isn't obvious there are helpful comments detailing almost anything I could wish to know. In my opinion, this is the way to do it. You don't have to painstakingly document every little class you write, just the "public facing" stuff. Not only does this help you or whoever else will be working with it in the future, it also documents the intent of the class/method much better than decent names can. People talk about "self documenting code", I haven't seen much of it. Most of the code I've seen fails miserably at being self documenting. Keep the "self documenting" internal. If you write a library to be used by other code, document the external API and leave the internals more loosely defined. At least that's what I want when I use someone else's library. I don't need some user manual that explains a few use cases I don't have, I just want simple, to the point, java docs that explain exactly what the code does, what the parameters represent etc. I can figure out how to put it together on my own if I just know what all the pieces do.
- deleted 3y ago[deleted]
- jinay 3y agoThat was actually another thing I gathered from the same internship. We had obnoxiously long variable and function names, but that meant our code read like English. Any comment would just be rephrasing how the code read aloud.
- sanderjd 3y agoComments aren't for "what does this code do?", they are for "why does this code do this?".
- Findecanor 3y agoYou are overgeneralising. There is bad commenting, yes, but you yourself listed several examples of when comments are needed: if we continued, this could be a long thread. Sometimes you need comments explaining an API that you are using, because its workings are not immediately obvious. Then the smell is not coming from your code but from the code you're calling.
- jackblemming 3y ago[flagged]