Timeline for How to avoid comments about one line of code for cleanliness
Current License: CC BY-SA 4.0
48 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| S Feb 16, 2020 at 15:11 | history | suggested | Jonathan Leffler | CC BY-SA 4.0 | Fix trivial typos |
| Feb 15, 2020 at 7:41 | review | Suggested edits | |||
| S Feb 16, 2020 at 15:11 | |||||
| Feb 14, 2020 at 21:36 | answer | added | erickson | timeline score: 3 | |
| Feb 14, 2020 at 6:00 | history | tweeted | twitter.com/StackSoftEng/status/1228197193594466306 | ||
| Feb 13, 2020 at 9:33 | comment | added | gnasher729 | Who says “comments should be used sparingly”? Add the comments that I need to know. All of them. | |
| Feb 8, 2020 at 19:19 | comment | added | EvilSnack | No matter how well a piece of code is written, it cannot tell you the most important piece of information of all: What the code is supposed to be doing. | |
| Feb 8, 2020 at 17:34 | comment | added | puck | Reading this question I checked the date, expecting it's April 1. of last year :-) You should not tear code apart by extracting a one liner to some other function somewhere else. And you should never expect someone to find and look at a commit in order to find out details of why you did X at code place Y. | |
| Feb 7, 2020 at 19:51 | history | edited | Deduplicator | CC BY-SA 4.0 | added syntax-highlighting |
| Feb 7, 2020 at 18:25 | answer | added | StackOverthrow | timeline score: 1 | |
| Feb 7, 2020 at 15:47 | comment | added | WGroleau | Comments do not harm maintainability. What hurts maintainability is an idiot who changes the code and doesn’t change obsolete comments. | |
| Feb 7, 2020 at 13:37 | comment | added | R. Schmitz | Don't go with "comments are almost always a bad idea". That's an extreme, just like "always write comments". What works well is "Comments are a failure to express yourself in code". You just can't always express yourself clearly in code. Comments are fine, but they're not something to be celebrated. That being said, if your method was just called AvoidArtifactsFirstFrame(), that seems like pretty clear communication to me. | |
| Feb 7, 2020 at 13:35 | comment | added | Spudley | The summary added to the end of the question is excellent. | |
| Feb 7, 2020 at 9:51 | answer | added | gidds | timeline score: 11 | |
| Feb 7, 2020 at 7:17 | comment | added | vsz | If you consider comments to be bad because of the danger of them not being updated when the code changes, consider how much worse it is if comments are embedded in function names, the behavior of the function is then later changed, but its name not updated... | |
| Feb 7, 2020 at 3:30 | comment | added | Lie Ryan | With good, well written code, comments are usually redundant and unnecessary. But that doesn't mean that comment is bad. Redundant comment is bad for future maintainability, because they're lines that have to be kept updated, so remove them. Once you've removed all the redundant comments, what you're left with are comments that are helpful in understanding the code. These generally tend to fall into documentation, overview, high level architecture notes, and warnings/pitfalls. | |
| Feb 7, 2020 at 2:17 | answer | added | Nat | timeline score: 2 | |
| Feb 7, 2020 at 1:15 | comment | added | Graviton | Does this answer your question? "Comment everything the right way" and "Instead of writing comments, write more readable code." - Both valid strategies? | |
| Feb 6, 2020 at 23:35 | answer | added | Karl Bielefeldt | timeline score: 2 | |
| Feb 6, 2020 at 21:33 | answer | added | Adrian McCarthy | timeline score: 0 | |
| Feb 6, 2020 at 21:13 | comment | added | donjuedo | If you avoid comments in your code, I will avoid your code | |
| Feb 6, 2020 at 20:14 | history | edited | Adam B | CC BY-SA 4.0 | spelling |
| Feb 6, 2020 at 20:05 | history | edited | Adam B | CC BY-SA 4.0 | added 180 characters in body |
| Feb 6, 2020 at 17:50 | answer | added | Bill K | timeline score: 0 | |
| Feb 6, 2020 at 17:31 | history | protected | gnat | ||
| Feb 6, 2020 at 16:27 | comment | added | Mark Rogers | There are two very divide camps on comments for always verbosely commenting to only writing self-documenting code and every view in between. I just follow whatever my employer and the power structure prefer because I can go either way on the issue. | |
| Feb 6, 2020 at 15:43 | comment | added | Erin B | your example sounds like it should be a "todo:" comment, imo. | |
| Feb 6, 2020 at 15:05 | comment | added | Stack Exchange Broke The Law | Don't forget a LineRendererDisabledStateStarterToAvoidArtifactsFirstFrameFactoryRegistry so we don't have to hardcode how the LineRendererDisabledStateStarterToAvoidArtifactsFirstFrame is instantiated. | |
| Feb 6, 2020 at 15:04 | comment | added | Stack Exchange Broke The Law | It's even worse because now this object has multiple responsibilities (it starts the line renderer disabled to avoid artifacts on the first frame, plus whatever it usually does). Don't you need to create a LineRendererDisabledStateStarterToAvoidArtifactsFirstFrame class? | |
| Feb 6, 2020 at 13:21 | comment | added | cmaster - reinstate monica | Your example is one of the most valuable comments, imho. Just keep it. | |
| Feb 6, 2020 at 11:33 | comment | added | Tvde1 | Comments do not really help with "what is this doing" (too complex = break down, not use comments) but help with "why does this happen" (e.g. describe edge cases). | |
| Feb 6, 2020 at 3:27 | comment | added | jamesqf | Your "name" is just a comment with the spaces removed. | |
| Feb 6, 2020 at 3:02 | comment | added | Harper - Reinstate Monica | read that comments are almost always a bad idea for future maintainability Who is the "they" who said that? It's too bad "they" aren't gun safety educators. Darwin would take care of this for us :) | |
| Feb 6, 2020 at 2:45 | comment | added | Fabio | ...but this doesn't seem all that clean to me - trust your self, if it doesn't seem clean - don't do this. Remember there are no absolute rules in software development - use right tool for the job in the current context | |
| Feb 6, 2020 at 2:44 | comment | added | joshp | Change the word "will" to "must" and call it a great comment. Don't let 'best practices' override your conscience and common sense. | |
| Feb 6, 2020 at 2:18 | comment | added | Cody Gray | This is one of the many uses of RAII. If your language of choice doesn't support RAII, that is very sad. You should upgrade to a language that does. Then, you can offload this setup and teardown work to a helper class, reducing the amount of code you have to write and comment. As an even bigger bonus, you don't have to worry about exception safety. | |
| Feb 6, 2020 at 2:15 | answer | added | Graham | timeline score: 50 | |
| Feb 6, 2020 at 2:06 | comment | added | Alexei Levenkov | @MartinK Are you essentially saying that "comment why, not how" is not a best practice? (which is fair opinion, I just always consider it to be one... something like blog.codinghorror.com/code-tells-you-how-comments-tell-you-why) | |
| Feb 6, 2020 at 1:06 | history | became hot network question | |||
| Feb 5, 2020 at 22:35 | vote | accept | Adam B | ||
| Feb 5, 2020 at 22:18 | answer | added | Richard Haven -- Virta Health | timeline score: 5 | |
| Feb 5, 2020 at 19:01 | vote | accept | Adam B | ||
| Feb 5, 2020 at 22:33 | |||||
| Feb 5, 2020 at 18:27 | answer | added | Roger | timeline score: 8 | |
| Feb 5, 2020 at 18:13 | answer | added | GrandmasterB | timeline score: 190 | |
| Feb 5, 2020 at 17:40 | answer | added | FluidCode | timeline score: 16 | |
| Feb 5, 2020 at 17:30 | comment | added | Martin K | There is nothing wrong with comments explaining the code if there no better way to convey that information. Best practices don't cover everything. | |
| Feb 5, 2020 at 17:25 | review | Close votes | |||
| Feb 14, 2020 at 3:05 | |||||
| Feb 5, 2020 at 17:03 | answer | added | Thomas Owens♦ | timeline score: 78 | |
| Feb 5, 2020 at 16:57 | history | asked | Adam B | CC BY-SA 4.0 |