[HN Gopher] Why Not Comments
___________________________________________________________________
Why Not Comments
Author : ghewgill
Score : 72 points
Date : 2024-09-10 20:52 UTC (2 hours ago)
(HTM) web link (buttondown.com)
(TXT) w3m dump (buttondown.com)
| gary_0 wrote:
| The title might be clearer with a hyphen: "Why-Not Comments".
| kstrauser wrote:
| The title's a little odd, unless it was to grab attention. It's
| saying "Why [I use] 'not comments'", not asking "why not
| comments?" A "not comment" here is an explanation of why the
| programmer didn't choose the obvious approach. I agree: that's a
| very valuable thing to document for the next person.
|
| For instance, you might write something like: # I
| used a bubble sort instead of a quick sort here because #
| the constraint above this guarantees there will never be #
| more than 5 items, so it's faster to use the naive #
| algorithm than to implement a more complex algorithm that #
| involves more branching.
|
| or # Normally we'd do X, but that broke customer
| Y's use case # based on their interpretation of our API
| docs which we # had kind of messed up. So now we do Y
| because it works # under both interpretations, at least
| until we can get # them to upgrade.
|
| Basically, tell your audience why you're not using the expected
| method. It's not because you didn't know about it, but because
| you do know and you've determined that it's not a good fit for
| this use case.
| lkrubner wrote:
| The problem with the title is simply that the English language
| allows open compound words. I know many Germans wonder why we
| allow this. Germans push the words together, for clarity. I've
| suggested that we use hyphens. Hyphens feel natural in English,
| and could remove the ambiguity that exists whenever we use open
| compound words (that is, open-compound-words). In this case
| "not-comments" would have added clarity.
|
| Likewise, the title "World's longest DJ set" was confusing,
| because most people will assume that the compound word is "DJ-
| set". But if you read the whole article, then you realize that
| a python snake fell on the mixing board and accidentally mixed
| some tunes. So the compound word was actually "longest-DJ" -- a
| 2.5 meter python.
|
| We should all consider using hyphens for all compound words.
|
| https://x.com/krubner/status/1828155852773113942
| BobaFloutist wrote:
| I think the "Longest DJ Set" was intentional wordplay.
| thayne wrote:
| As was the title of this article.
| aidenn0 wrote:
| As always, there's a relevant xkcd: https://xkcd.com/37/
| thayne wrote:
| I think the title is intentionally ambiguous.
|
| Because the article is a rebuttal to those who oppose writing
| comments (that is where "why not comments" means "why you
| shouldn't write comments") where the main argument is that you
| should write "why not" comments (that is "why not comments"
| means write comments explaining why you didn't do something or
| do something a certain way).
| JohnMakin wrote:
| I often write comments like this when I can predict what an
| overly nitpicky reviewer will say in a code review - "I didn't do
| X because Y" hoping to save some annoying back and forth about
| it.
| lainga wrote:
| IME you get the same amount of back and forth but I get to
| write "as the comment says" a few times
| JohnMakin wrote:
| LOL precisely
| rplnt wrote:
| I add those preemptively in the PRs, but not sure they have
| much value in the code.
| not2b wrote:
| They have value in the code because they save time when
| someone has to deal with that code a couple of years later.
| Certainly the explanation could be in the code reviews or the
| commit message, but it's easiest if it is right there.
| panopticon wrote:
| Yup. Our operating principle was that if a question was
| asked in a code review, someone will likely have the same
| question when reading the code weeks/months/years from now
| and there should be a comment.
| Terr_ wrote:
| > Does 16 passes over each string BUT there are only 25 math
| strings in the book so far and most are <5 characters. So it's
| still fast enough.
|
| Another twist on this is to put in a debug logging statement
| which triggers when the inputs are much larger than the original
| design constraints.
|
| It's roughly the same message to a future-developer, but they
| might find it much sooner, short-circuiting even more diagnostic
| and debugging time.
| ok_dad wrote:
| This is a great idea for a lot of things! Sometimes I will
| write a loop I know is slow as hell but works for now, and it
| would be cool to use a timer and do, "if this takes more than X
| seconds, log a warning." I mean, the perfect logging and
| observability should theoretically time all the components of
| your app, log debug information often, and etc., but who really
| uses a perfect system like that? I think it's more important to
| make specific effort to log in areas where performance might
| suck later or where you didn't have time to optimize or do
| exactly what you wanted to do.
|
| Your comment is super obvious, in hindsight, but I never
| thought to do something like this, usually at past places of
| work we've just agreed to make a comment on things we need to
| reconsider later and hopefully we remember about that comment
| when things go downhill!
| AlotOfReading wrote:
| I find that a lot of well-meaning tools (e.g. bazel) regard
| non-error output as noise to be hidden. They'll often route any
| messages like this to the nearest wastebin they can find, which
| makes logging incredibly unreliable as a means of communicating
| constraints in some domains.
| ghewgill wrote:
| I agree that the title is ambiguous - it's what piqued my
| interest to read the article in the first place. Personally I
| lean toward fewer comments overall - perhaps to a fault - but
| explanatory comments as shown in the article are absolutely
| valuable. It's a good reminder to explain the whys and the why
| nots.
|
| This especially applies to your own code that you write and still
| have to maintain 5, 10, 15 years later. Just the other day I was
| reviewing a coworker's new code and thought "why choose to do it
| this way?" when the reason was 10 lines up where I did it the
| same way, 8 years ago. She was following the cardinal rule of
| maintenance - make the code look like the existing code.
| sparrish wrote:
| > make the code look like the existing code.
|
| This is so undervalued when maintaining an older codebase.
| Please, for the sanity of those who come after you - make the
| code look like the existing code.
| ufo wrote:
| When I see a sequence of string replacements, instead of
| performance the main thing I worry about is if the output of one
| replaces matches a pattern for another replacement. I see
| variations of this often during code review.
|
| Doesn't seem to be a problem here though because they're
| replacing macros by symbols that are known ahead of time.
| remot_human wrote:
| Maybe what we need is a single vocabulary word that means "I'm
| doing something that won't scale well to large inputs but is
| still worth writing for now" then you could name the function
| replaceEscapeCharsNewWord()
| Jtsummers wrote:
| I've named these things "naive" sometimes. Like
| "naiveQueryBuilder" or whatever the appropriate term would be.
| They're also useful for creating tests because the naive
| version is usually "obviously" correct (still write some tests,
| but you don't need much more than sanity checks) and can be the
| oracle for the faster version (you might want to cache results
| rather than run the naive one each time, though).
| xelxebar wrote:
| Ithkuil to the rescue? https://en.wikipedia.org/wiki/Ithkuil
| 8organicbits wrote:
| Another approach is ADRs, which document alternatives considered,
| but these are documentation, not comments. I've found them useful
| for building consensus around architecture decisions.
|
| https://adr.github.io/
| keybored wrote:
| You can still document the why in commit messages![1]
|
| I feel like I'm getting off the self-documenting code ride. In
| our own codebase we rely way too much on "descriptive names".
| Like full-on sentence-names. And is the code self-documenting?
| Often not. You indeed cannot describe three or more axes of
| concerns in one name.
|
| Do comments go stale? Well why does it? Too loose code reviews?
| Pull requests that have fifty lines of diff noise that you glaze
| over? We have the tools to do better on that front than some
| years ago at least.
|
| It's a joy to find a corner of the code base where things are
| documented with regular sentences. Compared to having to puzzle
| through five function call layers.
|
| [1] But yeah, really. But also: sometimes also in comments.
| Sometimes both.
| klingoff wrote:
| Right, commit messages are at least always right for the
| context that comes with them. I think long descriptive names
| are an anti pattern. As per word puzzles you can't actually
| read the middle of a blob of text so you are basically left
| with a dozen variables that are cognitively the same as
| isDatabaseHidingDragonsSetter().
| oxidant wrote:
| I mostly like a comment with a succinct explanation and a
| longer commit message. Comments are less likely to be
| refactored and lose the immediate git blame, while the function
| might change over time.
|
| Ideally the future user would trace the git blame back to the
| original commit of they really had questions.
|
| A long comment is really helpful sometimes though. I like to
| put ascii truth tables for complex boolean logic, both to
| ensure I cover all cases when writing the code (tests, too) and
| to make it easier for future me to understand what's going on
| at a glance.
| ok_dad wrote:
| I personally don't care what anyone says, I use comments and doc
| comments ALL OVER the place; I do it in reverse, though. I write
| a list of steps for the application as comments, a rough draft at
| first, then as I develop the code I take the big steps and split
| them into little steps, sometimes removing the original comment
| and sometimes not, and I continue to split comments into smaller
| steps until I have nearly a complete algorithm. Then I just code
| the logic in there. I normally will code from the outside in, so
| I'll also be writing code as I do the comment-splitting stuff.
| Sometimes I get off on a tear and I code a bunch of stuff at
| once, but then later I go back and comment it down to a level
| that I think most of you would find annoying. Every function and
| variable has a comment about what it does, even the `deg_to_rad`
| function has a comment `"""Converts degrees to radians."""`. Why
| not, storage is cheap!
|
| I know most people don't like it, and that is fine, they can deal
| with it! I they don't want to see my comments, they can remove
| them from their version of my code with a script, and if my co-
| workers and boss don't like them they can remove them in a code
| review! However, I can say that I enjoy reading my old code way
| more than I enjoy reading other's code which have zero comments.
| I work in Python, so a lot of the simple non-algorithm code
| (boilerplate stuff for apps, like flask APIs for example) is
| mostly "self-documenting" since the old saying goes, "write some
| pseudo-code and 95% of the time it runs in Python." The most
| important comments are sometimes on the boilerplate stuff because
| that's where a lot of changes happen versus the algorithms where
| I find there is a lot more wholesale rewriting in my industry.
|
| I will always love comments and doc comments!
| buggy6257 wrote:
| > I know most people don't like it, and that is fine, they can
| deal with it! I they don't want to see my comments, they can
| remove them from their version of my code with a script, and if
| my co-workers and boss don't like them they can remove them in
| a code review!
|
| It was all great until you got here. This is a big red flag for
| me for a teammate.
| gleenn wrote:
| Comments are great when they are well maintained. But for every
| codebase that isn't basically some open source software where
| the eyeballs-reading to comment-maintaining ratio is really
| high and people spend the time, everyone eventually forgets
| and/or is too lazy to maintain them. It can be almost as much
| work updating the comments as adjusting the code a lot of the
| time. So the ground truth reality is that comments are usually
| "lies waiting to happen". Eventually, the comments and the code
| won't be in sync, and this can be potentially worse than having
| either bare, uncommented code, or better, having actual
| automated tests that show intent. The tests mostly can't lie,
| otherwise you wouldn't have merged them presumably. If you show
| me a bunch of decent tests laying out how the code is intended
| to be used, _that_ is what I want to see. Because it is
| explanatory AND it is nearly guaranteed to be truthful.
| rich_sasha wrote:
| I never found that to be a problem in practice. Yes, comments
| do get slightly out of sync, and not always corrected. But
| typically enough comments are correct that you can make sense
| of the whole thing, and can even fix the comments then.
|
| By contrast, I have really never seen truly self documenting
| code. The comments may be up to date by virtue of not
| existing, but the end result is just more confusing. YMMV
| pavon wrote:
| I'll take the out of date comments. They provide a red flag
| that either the original author was confused, or the behavior
| changed over time. At least then you can do code archeology
| to piece together descriptions of what the original intent
| was, and how it changed using the commit history and figure
| out where things went off the rails, and thus determine how
| to actually fix it rather than patch over it even worse.
|
| The problem with unit test as documentation is that over time
| they end up reflecting the same misconceptions that the code
| has. Someone does a refactor, misunderstands how the original
| code works, and "fixes" the unit tests to pass. Now you have
| tests that lie just like comments can lie.
| AcerbicZero wrote:
| Hah, this is me :)
|
| Half the time I start by just writing comments explaining what
| I'm about to try and do, then I go back and add comments about
| how things did not go as expected, and what I had to do to get
| it to actually work. Super helpful 5 weeks later when I have to
| actually see it again.
| mentalgear wrote:
| An article not not to overlook.
| jerhewet wrote:
| Comments should never be "what". They should always be "why".
| zimpenfish wrote:
| That works if the code wasn't written by, well, lunatics who
| decided that clear simple code was The Work Of Satan and if you
| couldn't have a tower of interfaces or write your own
| bafflingly complex ORM, what was even the point? Then the
| people who follow will almost certainly need some "what"
| commentary (as well as the "why" but IME the lunatics who spurn
| clear and simple code never think they have to explain "why"
| either.)
| mschuster91 wrote:
| > or write your own bafflingly complex ORM
|
| Oftentimes, the reason for that is that 20 years ago stuff
| like Doctrine, Liquibase or whatever _just didn 't exist_.
| You know, the time when PHP developers shipped straight
| mysql_query calls with direct interpolation of $_GET, and
| most "enterprise" Java application came with a ton of SQL
| scripts and a dedicated multi page UPGRADE file explaining in
| which order you had to run the schema migrations, reboot
| systems, run manual migration scripts and whatnot to get an
| upgrade done. Some times, upgrades could literally take
| _days_.
|
| Naturally, people invented their own stuff to make stuff just
| suck a little bit less, and it got more and more used in a
| company, only ever extended in functionality... the dreaded
| "corpname-utils" JAR dependency (if you're really unlucky,
| the JAR having been semi-restored from a half-broken
| decompile because the sources got lost along the way) or
| util.php that just got copied over from project to project.
| And that's how you end up in 2024, still maintaining some ORM
| that has its origins in Perl code written in the 90s by
| someone deceased in the '00s. (Yes, I've been there, although
| not _that_ bad)
| edflsafoiewq wrote:
| Comments should be whatever you think warrants commentary. If
| that's "what", that's fine.
| renhanxue wrote:
| I saw someone quip (on twitter, I think) many years ago something
| like:
|
| "A junior engineer writes comments that explain what the code
| does. A mid-level engineer writes comments that explain why the
| code does what it does. A senior engineer writes comments that
| explain why the code isn't written in another way."
|
| (except punchier, of course. I'm not doing the quip justice here)
| abc-1 wrote:
| I do all of the above. Summary comments are incredibly helpful
| and have been validated by empirical research. Too bad many
| have drunk deeply from the Clean Code koolaid and can't be
| saved.
| Prickle wrote:
| I was taught to not leave comments in finished code.
|
| I have regretted following that lesson ever since.
| acbart wrote:
| If code were ever finished, then perhaps this would make
| sense :)
| spacechild1 wrote:
| Who taught you that!?
| readthenotes1 wrote:
| I have regretted when you fail to follow that lesson.
|
| I did a survey once in about 3/4 of the comments were
| either wrong or useless. Examples:
|
| //Add 1 to x
|
| x+=1;
|
| //Add 1 to x
|
| x+=2;
|
| //Seconds per normal day
|
| x = 86400;
|
| --
|
| "Why not" comments are incredibly valuable except they
| suffer from explanatory decay as much as other comments.
|
| The hope behind Intention Revealing Names is that the
| dissonance will be too great for the subsequent developers
| to ignore when they change the code.
|
| Of course, that isn't always true.
| __MatrixMan__ wrote:
| I like two of the three, but what is the advantage of
| commenting what the code is doing, when you can use a Trace
| or Debug message for that instead?
| PlunderBunny wrote:
| Not the person you are replying to, but I would say that:
|
| - The code 'tells you' what it does
|
| - The comment for the code tells you what the author
| intended it to do.
|
| The gap between the two is where bugs can be found.
| edflsafoiewq wrote:
| A function generally tells you what it does three times:
| once in the doc comment, once in the function name, and
| once in the body.
| seanmcdirmid wrote:
| We could have the best of both worlds if comments could be
| easily hidden, or better yet, just additional meta-data on
| rich text code. But nope, we can't get away from ascii.
| mschuster91 wrote:
| > A senior engineer writes comments that explain why the code
| isn't written in another way.
|
| And C-level engineers write a comment "X hours have been wasted
| on refactoring this code. Should you decide following the
| example of your priors, please increment this counter."
|
| Sometimes, even what appears to be an utter hack job _actually
| is_ the best you 're gonna get.
| breck wrote:
| I resisted putting comments in my languages for years. My
| reasoning was it was always a flaw of my code (or the language)
| if I couldn't express myself in typed code.
|
| Then I realized that my languages will never be perfect, and
| having comments is an essential escape hatch. I was wrong and I
| changed my mind.
|
| Also, 99.9% of languages have comments:
|
| https://pldb.io/blog/a-language-without-comments.html
| icambron wrote:
| The "why not" form just seems to be a special case of "explain
| why this code is weird", which is my commenting metric in its
| entirety
| golergka wrote:
| > This is incredibly inefficient and I could instead do all 16
| replacements in a single pass. But that would be a more
| complicated solution. So I did the simple way with a comment: >
| Does 16 passes over each string > BUT there are only 25 math
| strings in the book so far and most are <5 characters. > So it's
| still fast enough.
|
| I've been in this exact situation quite a few times -- use a bad
| algorithm because your n is low. However, instead of commenting,
| I did something like this instead: function
| doStuff(items: Item[]) { if (items.length > 50) {
| logger.warn("there's too much stuff, this processing is
| O(n^2)!"); } // ... do stuff }
| Wowfunhappy wrote:
| > When I was first playing with this idea, someone told me that
| my negative comment isn't necessary, just name the function
| RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs.
|
| Wow, someone actually suggested that?! Do people write whole
| programs like this?
| mkoubaa wrote:
| This is griefing your coworkers who would actually do that?
| Wowfunhappy wrote:
| I wasn't being sarcastic, if that's what you meant. (And I'm
| not a professional programmer so I don't have coworkers who
| write code.)
|
| To me, the suggestion seems so incredibly bad that I am
| literally trying to understand the headspace of someone who
| would suggest that. Like, is it less bad than it seems,
| somehow?
| GuB-42 wrote:
| I'd say that it is one of the few cases where comments are the
| best solution.
|
| You can't have functional code for what isn't done, so that's
| some information you can't express in code.
|
| Furthermore, a major problem with comments is that you can't
| debug or test them. There are many tools that can analyze code,
| static or runtime, but because comments are just free text, you
| can't do much besides spellchecking. Also it is common to forget
| to update comments, and with the lack of testing, in the end, you
| get lies.
|
| But here, the only maintenance these comment need is to remove
| them if they stop being relevant. For example because you finally
| did the thing you said you wouldn't do, or just scrapped the
| part. Very low effort, also rather easy to spot, since if you see
| a thing being done with an explanation on why it is not done, it
| means someone forgot.
|
| It is also worthwhile because as programs grow, they tend to do
| more, and "not" assumption may no longer hold (there used to be 4
| parameters, now there are 10000...), meaning it is something you
| should check.
|
| A lot of slow code comes from an assumption that N will be small,
| and N ends up being big. By the way, that's why I favor using the
| lowest O(n) algorithm that is reasonable even if it is overkill
| and slower on small sets. Because one day, it may not be. If for
| some reason, using a low O(n) algorithm is problematic, for
| example because the code is too complex or the slowdown on
| smaller sets too great, then comes the "why not" comment.
| bulatb wrote:
| People who will not admit they're bad at something will invent
| some reason that the thing is bad, and, actually, it's good to be
| bad at the thing.
|
| Writing good comments is hard. Switching into writing mode from
| code mode can be hard. Just admit it. Ego ruins everything it
| touches, so don't let it touch your work.
| AcerbicZero wrote:
| I have learned to enjoy narrating my struggles in the comments,
| probably to excess; but it certainly makes it much easier to pick
| up a task again after I leave it alone for a week or two.
|
| People rarely touch what I write, but if they do, and they want
| to strip the comments out, thats totally fine with me, just don't
| ask me how it works after you do :P
| slaymaker1907 wrote:
| > In recent years I see more people arguing that whys do not
| belong in comments either, that they can be embedded into
| LongFunctionNames or the names of test cases.
|
| Who is arguing this? Usually, if I'm adding a comment on why
| something is done a particular way, it's something that is going
| to take at least a full sentence to explain if not a whole
| paragraph.
___________________________________________________________________
(page generated 2024-09-10 23:00 UTC)