Timeline for How can I deal with a team member who dislikes making comments in code?
Current License: CC BY-SA 3.0
9 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Nov 25, 2024 at 21:37 | comment | added | gnasher729 | Where you absolutely need comments is when there is no code. Say at some point it is obvious that x should be increased - except for some very non-obvious reason this would be wrong. If I write the correct “no code” the next programmer will see an obvious mistake and “fix” it, breaking the code. So a comment why there is no code is absolutely needed. | |
| Mar 1, 2013 at 2:55 | comment | added | Nux | Even if you use ridiculously long variable names the code itself won't tell you why something was done. E.g. based on what kind of requirements ("using function X because Y is much faster in Chrome 9" - tells you to test against Chrome if you refactor the code) or which requirements the code was made like so ("for a client no. 54321, see bug #1234; it's stupid, but he paid $10.000 for it so don't break it" - it might sound funny, but this kind of comments let you avoid a lot of serious real-world problems and fast re-releases). | |
| Feb 17, 2013 at 11:48 | comment | added | GordonM | Clean Code is a decent book, but it should not be treated as gospel. You have to apply common sense and decide for yourself what works. I disagree with the advice on comments, because programming languages are geared towards expressing the how of a problem with scant regard to the why. I was writing code for Google Shopping that appends a country code to the product SKU. It's obvious what the code is doing, but unless you know that you can only use the same product code once, even in different markets, you wouldn't know why I was doing this. The comment I added clarifies it. | |
| Feb 8, 2013 at 8:59 | comment | added | user11463 | While comments in code would not be necessary, there should be at least the method description, such as Javadoc | |
| Feb 6, 2013 at 16:45 | comment | added | bharal | always had a problem with that book's approach. Comments can be v. useful in explaining a business process/logic (or why) that no amount of clean code can. | |
| Feb 6, 2013 at 14:13 | comment | added | Dunk | Re: "this kind of forcing will most probably result in horrible comments". If you aren't commenting as you code then back-filling comments after the code is done will almost always result in horrible comments whether you believe in them or not. When you are coding, that is the time that you know exactly WHY you are doing something a particular way. That's the time to let others know. If you comment after you're done, odds are you won't even remember what you were thinking when you wrote the code, so you tend to throw a useless comment in just for the sake of commenting. | |
| Feb 6, 2013 at 13:16 | comment | added | Sparky | +1 for discussing the actual profits from comments. Comments are meant to add value to the source code. | |
| Feb 5, 2013 at 20:54 | history | made wiki | Post Made Community Wiki by Danny Tuppeny | ||
| Feb 5, 2013 at 6:32 | history | answered | Frank | CC BY-SA 3.0 |