[HN Gopher] Why Not Comments
___________________________________________________________________
Why Not Comments
Author : ghewgill
Score : 239 points
Date : 2024-09-10 20:52 UTC (1 days 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/
| shiroiushi wrote:
| >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
|
| We _do_ use hyphens in English. Well, some of the time, and
| some of us. I could be wrong, but I do feel that, given my
| age and also my readings of older texts, that the use of
| hyphens in this way has become less common, and that this was
| much more common decades ago to avoid ambiguity.
| Tainnor wrote:
| "longest DJ" isn't a compound, it's a noun modified by an
| adjective, and as such it would be written as two different
| words in German as well ("langster DJ").
| 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.
| TillE wrote:
| It's an obvious cliche, but that "someone" is very
| frequently you. It's really easy to forget why you made
| some non-obvious decision and waste time poking at the
| exact same stuff you already did a year or two ago. It's
| happened to me several times.
|
| When you figure out something tricky, leave a comment.
| JohnMakin wrote:
| completely agree every person who leaves detailed
| "unneccessary" comments like this has been bitten by
| coming back to a codebase a year+ later and going "who
| was the idiot that wrote this and why didnt they leave
| any clue behind" and realizing that yes, you were the
| idiot. or has had to come behind someone that left zero
| documentation or readable code and been tasked with
| cleaning it up. breadcrumbs are useful and comments cost
| nothing. yes, there are commit messages, but commits
| often aren't super clean, explicit, coherent, or even
| looked at.
| 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!
| Terr_ wrote:
| I'd caution that it's a very "80/20" thing, since the
| cost/complexity of detecting all "unusual" cases can easily
| become not-worth-it.
|
| For example, if the slowness of the method depends on non-
| trivial aspects of the input, or if the performance problem
| in production comes from someone calling your method too many
| times on (individually) reasonable chunks of data.
| 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.
| Terr_ wrote:
| I'm thinking the log message is something you wouldn't want
| to trigger in production anyway, unless you're pretty
| confident that it won't lead to a ton of spam on the day that
| inputs rise over the threshold.
|
| Using a debug log-level helps prevent that problem from
| occurring in production, while still making it visible to
| developers that have more logging enabled in their dev/test
| environments.
| 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.
| sbuttgereit wrote:
| "Please, for the sanity of those who come after you - make
| the code look like the existing code."
|
| I think it's a great rule of thumb... but there are
| exceptions.
|
| For example, Funnily enough I was reviewing some code just
| today written by someone else and that I'm going to be asked
| to expand on or maintain. It looks like this:
| var example1 = Object; var example2 = Object; var
| example3 = Object; ... var example147 = Object;
|
| And then later there are corresponding variables assigned to
| different objects which are: var tempExample1
| = <some object instantiation>; var tempExample2 = <some
| object instantiation>; var tempExample3 = <some object
| instantiation>; ... var tempExample147 = <some
| object instantiation>;
|
| And this goes on and on. It's real special once we get into
| the real business logic. (and to be clear... "example1" are
| the actual names, I'm not just obfuscating for this comment.)
|
| The reason it looks like this is because the original
| developer copied the examples from the developer technical
| documentation for what they were doing verbatim; this
| documentation only had one variable so the numbering was the
| way to get multiple variables. Knowing this system, they
| didn't have to do that, they could have very easily assigned
| meaningful names for all of this. (To be fair, the original
| developer isn't a developer but a consultant business
| analysist saying, "Oh yeah, I can do that!" to the client....
| billing all the way).
|
| I can tell you with great certainty and righteousness: I'm
| not going to make my code look like the existing code. I may
| well do some refactoring to make the existing code vaguely
| scrutable.
|
| I appreciate that what I'm describing is an extreme case and
| not really what you or parent comments really were
| addressing. I just stop to point out that what you describe
| is a rule of thumb... a good one... but one nonetheless. And,
| as an absolute rule of thumb about rules of thumb, there are
| no absolute rules of thumb. Ultimately, experience and
| judgement do matter when approaching the development of new
| code or decades old code.
| PeterisP wrote:
| The concept of "make the new code look like the existing
| code" still applies - in the example you gave, if you need
| to add examples148-200, and want to do it in a better way,
| then it would be wrong to do that new way for the new code;
| either you are willing and able to refactor the previous
| 147 cases as well (so that the new code matches the
| existing code, because the existing code was updated), or
| you keep the existing structure.
| Tainnor wrote:
| Unless of course you work in a wild-west codebase where you
| can basically tell who wrote what code because everyone has a
| distinct style and they never converge. ugh
| 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.
| ok_dad wrote:
| Well I don't think we'll end up being teammates, and I
| haven't had issues before :)
| 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
| awfulneutral wrote:
| Same, my coworker used this argument when I tried to get
| them to write more comments. The number of hours I've
| wasted due to there being no comments at all is way, way,
| way more than the very small number I've wasted due to a
| no-longer-accurate comment. And I usually find that people
| who write self-documenting code choose variable/function
| names that might make sense to them at the time, but are
| vague and confusing to me when I need to read the code.
| bottlepalm wrote:
| Same here as well, I hear this argument a lot, but have
| yet to see a comment I didn't appreciate. And if there's
| something wrong with the comment, fix it! Self
| documenting code is a joke.
| 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.
| gleenn wrote:
| Neither comments nor lacking unit tests are going to fix
| that, that's a strawman argument. What I'm saying is if
| someone doesn't know 100% what their doing, which can be
| relatively often, then I would hands-down take a bunch of
| unit tests over some misguided comments because at least
| the unit tests have to /pass/, so there is some grounding
| in reality. A comment has absolutely no such requirement
| and therefore can stray in any direction forever. Also, if
| you refactor a name of a variable or inputnor function, you
| will be required to update the tests, so they are dar safer
| from becoming stale due to refactoring compared to an
| opaque string from the IDE's point of view.
| Salgat wrote:
| Code that breaks is much more likely and damaging than
| comments that are out of date. In my life I've never had a
| case where the bad outweighed the good for comments.
| kmoser wrote:
| Also, if you're doing regular code reviews, wouldn't that
| include making sure the comments are up-to-date?
|
| As for the argument that it wastes time to update comments,
| I've never seen a codebase where the comments were so
| voluminous that it would be a significant burden to update
| them. Devs avoid updating comments because there is usually
| no penalty for doing so (boss doesn't call them on it, and
| the code still runs), and they think they've saved a few
| minutes when in fact they're just kicking the can down the
| road for the next dev who has to decipher the incorrect (or
| missing) comment.
| 8n4vidtmkvmk wrote:
| No. If the comment isn't highlighted in green or red in
| the commit, I'm not likely to read it.
| PeterisP wrote:
| Well, that's a problem.
| 8n4vidtmkvmk wrote:
| Code breaks because people read the comment and assume it
| speaks truth when in fact it's full of lies. And as soon as
| you don't trust comments you have to start reading the
| code. And if you're at that point now..... Why have the
| comment?
| bottlepalm wrote:
| Comments don't replace reading code, they prime your
| brain for the code you're about to read. There is often
| context and reason behind the code that is not in the
| code itself.
| Salgat wrote:
| If you ever trust comments over code you really need to
| adjust your approach. Comments are there to help guide
| you towards the intent of code, not to let you ignore
| code. Same reason why if a function has a bug, you don't
| ignore that bug just because the function's doc says
| otherwise.
| 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.
| slaymaker1907 wrote:
| I don't think doc comments are warranted in every case and
| definitely don't think you need to document every single
| parameter, return value, etc. for every single function, but
| they sure do come in handy for complicated APIs.
| lifthrasiir wrote:
| I also tend to do so but _only for top-level constructs_ ,
| where such comments are most useful. I think I do so because I
| like to conceptualize entirely within my mind; I found it
| rather slow to experiment with various design choices by
| actually writing them down, at least initially. So I
| necessarily have to document these design choices once they are
| settled (as others don't yet have access to my mind :-), while
| I expect details become much clearer after others also have
| conceptualized them to their minds. This approach does have a
| downside of making it possibly harder to read when such
| conceptualization couldn't be done for any reason, so I do
| additional tweaking to maintain the baseline readability to the
| minimum required.
| bottlepalm wrote:
| Ah yes, Comment Driven Development (CDD), I practice it as
| well.
|
| You start with comments of how you want things to work, and
| fill in the code. It's a perfect combination of why/how and
| communicates to the next developer the high level thought
| process behind the code perfectly.
| phito wrote:
| You're wasting so much time doing this... Nobody will ever read
| 99% of it. Then the comments will get out of date and it'll end
| up worse than having no comments.
| mentalgear wrote:
| An article not not to overlook.
| mentalgear wrote:
| Actually, there's a not to much (it was late), it's definitely
| a great article !
| 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)
| pantulis wrote:
| > the dreaded "corpname-utils" JAR dependency
|
| In my first job, my older colleagues, most of them now
| managers, had managed to write their own library. It
| included its own timezone management, a wrapper o top of
| DEC's OSF/1 AXP concurrency primitives, a realtime memory-
| mapped database format, a compiler that run not on files
| but in expressions stored in an Oracle databse, and even
| their own CORBA-like object sharing over TCP/IP.
|
| These people were wizards, and probably did a lot of stuff
| just to show their coding prowess, but a decade later when
| I joined that company most of the younger programmers did
| not dare to touch that code. I had to do that when the
| software was being deployed in Brazil, where nobody had
| expected how DST changes in the south hemisphere.
| 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!?
| Prickle wrote:
| I was specifically taught that good, readable code could
| explain itself; that it would make comments redundant.
|
| Therefore, comments should only be used for things like
| psuedocode, or as help for fellow developers during dev.
|
| Then, they should be removed once the code is done.
|
| But yea, not a good idea.
| thayne wrote:
| This is an example of taking something that is
| contextually good advise, applying it to all situations,
| which turns it into bad advise.
|
| If you can make your code more clear, so that comments
| aren't necessary to explain what it does or how it works,
| that is probably (but not always!) something you should
| do. But that doesn't mean you shouldn't have comments. At
| the very least there should be comments explaining why
| (or why not) things were done a certain way.
| RandallBrown wrote:
| I have almost never run into a situation where a comment
| was better than a well named function or variable.
|
| It happens occasionally, but it's usually a sign that I'm
| doing something wrong.
| moring wrote:
| This is fine. A problem arises when you assume that this
| will always be the case, for all developers, and then
| mandate that they omit comments, _without checking if
| your assumption is true for their case_.
|
| IMHO that rule can be generalized: Whenever you make
| rules for other devs, make sure that the assumptions on
| which those rules are based are true, lest you interfere
| with their work in a negative way.
| atoav wrote:
| There are indeed those situations where a comment would
| not increase the clarity of the code.
|
| But one shouls be careful not to mentally think of this
| as a zero sum dichtomy, where you either have well named
| functions _XOR_ you have comments, because in reality
| choosingn both is often the golden path to success.
|
| The danger is of course that code that is totally
| _obvious_ to you _now_ will take far more time to become
| as obvious later, be it to your future self or to your
| psychopathic lunatic co-worker who knows where you live.
|
| So very often code can be made more readable by adding
| comments, even if it is just saying the same thing with
| other words, just by reducing ambiguity. Comments can
| also bridge higher level concepts in a good way, e.g. by
| you explaining in a few lines how a component fits into a
| concept that is spread out over multiple files etc.
|
| In the end code is text and like regular prosaic text you
| can both make it harder to understand by not mentioning
| things or by mentioning too many or the wrong things.
| This is why it is not irrelevant for programmers to be
| good and empathic communicators. Sure in the end
| readability doesn't matter to the computer, but it
| certainly matters to all people involved.
| exe34 wrote:
| well-named works great while you're writing the code.
| come back to it in a few years, or hand it over to
| somebody new, and you would realise that what looks like
| a good name to you means nothing to somebody else.
| netdevnet wrote:
| A line of code can tell you what it does but not why.
| Unless you are on a newish codebase, you will likely need
| comments to explain why certain decisions were made
| bccdee wrote:
| Really? There's a perfectly good example in the article.
| RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTra
| deOffs()
|
| That's a horrible way to name a function. Function names
| should be short, punchy, and unambiguous. They should
| create a simplified abstract narrative, and all the
| details should be put into the docstring, so that they
| can be easily accessible without having to (a) be
| squashed into an identifier, or (b) be repeated every
| time you want to call the function.
| atoav wrote:
| That is like saying: "A perfectly good road needs no road
| markings". The point of of good comments is that they
| make the code faster to read and less ambigous. While
| good code should indeed _already_ be readable and
| unambiguos, I have rarely seen code that couldn 't be
| made even easier to understand and faster to parse by
| writing the appropriate comment.
|
| But of course you will have some individuals who think it
| is cooler not to, and they are probably the same people
| who think use after free bugs can be avoided by the shere
| willpower of the solo-male-genius that they are.
| netdevnet wrote:
| Code explains the what but not the why. And even then,
| the what might not be so clearly obvious.
|
| This is one of those blindspots devs have in that they
| believe their code to be good and obvious to everyone but
| in reality it is not even good and obvious to their
| future selves who will be the ones maintaining that code
| dspillett wrote:
| _> I was specifically taught that good, readable code
| could explain itself; that it would make comments
| redundant._
|
| Good readable code removes the need for comments about
| what the code does, if the working of the code needs
| extra explanation then perhaps it is being too clever or
| overly terse, but there are other classes of comment that
| the code simply explaining itself can't cover.
|
| Some of my comments cover _why_ the code does what it
| does, perhaps linking it to a bigger picture. That could
| be as simple as a link to work ticket(s) which contain
| (or link to) all the pertinent details, though I prefer
| to include a few words of explanation too in case the
| code is separated from whatever system those work items
| are logged in.
|
| Many comments state why things were not done another way.
| This can be very similar to "why the code does what it
| does" but can be more helpful for someone (perhaps your
| future self) who comes along later thinking about
| refactoring. These can be negative notes ("considered
| doing X instead, but that wouldn't work because Y or
| interaction with Z" - if Y and Z become irrelevant that
| future coder can consider the alternative, if not you've
| saved them some time and/or aided their understanding of
| the bigger picture), helpful notes for future improvement
| ("X would be more efficient, but more complex and we
| don't have time to properly test the refactor ATM" or "X
| would be more efficient but for current use patterns the
| difference would be too small to warrant spending the
| time" - the "but" parts are not always stated as they are
| usually pretty obvious). A comment can also highlight
| what was intended as a temporary solution to mitigate
| external problems ("extra work here to account for X not
| being trapped by Y, consider removing this once that
| external problem is fixed" or "because X should accept Y
| from us but currently doesn't").
| f1shy wrote:
| IF the code is self-explanatory, then the comments are
| redundant, and is ok to delete them. But from time to
| time, there are things that are at least not so obvious
| in the code. Then is good to leave a comment.
|
| That could be used to see how good a language is for
| specific tasks. If you need to write lots of comments,
| maybe you have the wrong language.
| dodos wrote:
| I had a professor in college who would grade you down if
| there were any comments in your code.
| forgotpwd16 wrote:
| Perhaps professor was fed up with over-commenting
| (comments made up a large part of submitted code),
| especially if comments were like in
| https://news.ycombinator.com/item?id=41506466. Unless the
| course is "practical software engineering" or similar,
| that good programming practices are a focus, and if the
| why/why-not parts can contribute to better assessment, an
| associated paper can be asked.
| dspillett wrote:
| Sounds like a concrete example of the phrase "Those that
| can, do. Those that can't (try to) teach." Far from true
| for all teachers, of course.
|
| That and "those who actually use power are likely to be
| those who shouldn't have been given it"!
| 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.
| g-b-r wrote:
| An outdated comment is at least a very strong signal that
| the code might be wrong
|
| And, you definitely had little experience with under-
| documented code
| GianFabien wrote:
| For me the quality of comments, somewhat based on the
| metrics that @renhanxue mentions, is a code smell. If
| code is poorly commented (by my standards) then I treat
| the actual code with suspicion.
| dspillett wrote:
| _> An outdated comment is at least a very strong signal_
|
| Also: if the code and the comments appear to disagree,
| there is a reasonable likelihood that _both_ are wrong in
| some way.
| gus_massa wrote:
| x = 86400
|
| If I were forced not to write comments, I'd write that as
| x = 24 * 60 * 60
|
| and let the compiler optimize that.
| hansvm wrote:
| When writing it inline, I like this approach. I like even
| better when these things have names. Something like
| `std.time.s_per_day` or `time_utils.s_per_day`. Then in
| the one place they're defined, use a pattern like the
| above to make them easy to reason about.
| DanHulton wrote:
| One step further: DAY_IN_SECONDS = 24 *
| 60 * 60
| jjav wrote:
| > I did a survey once in about 3/4 of the comments were
| either wrong or useless.
|
| > Examples:
|
| > //Add 1 to x
|
| > x+=1;
|
| If 3/4ths of comments are like this, maybe show a
| sampling of public source code (e.g. from github) that
| shows how prevalent comments like this are in any real
| codebase.
|
| I've been programming since 1982 and have never seen this
| type of "add 1 to x" comment in real code, outside
| chapter 1 of some intro to programming book.
| dllthomas wrote:
| I once came to a complicated, multi threaded C++ program
| and saw: using namespace std; // using
| namespace standard
| f1shy wrote:
| I'm working RIGHT NOW in a codebase where before each
| function definition there is a comment "// Function"
| bccdee wrote:
| I wonder if that's intended for a specific workflow, e.g.
| ctrl-f "Function" enter-enter-enter-enter to cycle
| through all the functions in the file.
|
| That's the only reason I can think of for writing those
| comments.
| imp0cat wrote:
| Code is never finished, only abandoned.
| hi_hi wrote:
| If you're commenting out code, don't
|
| If you're commenting about the code, do.
|
| There's a huge difference in the value between one or the
| other.
| __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.
| readthenotes1 wrote:
| "The comment for the code tells you what the author
| intended it to do."
|
| Not quite.
|
| The comment for the code tells you what the author of the
| comment understood the code to do when hen wrote the
| comment.
| PlunderBunny wrote:
| It could be that too, but I think that presumes an order
| - that the comment was written after the code. If the
| comment was written before the code, then it would
| describe what the author was trying (intended) to do.
| Which also implies an order of course.
| g-b-r wrote:
| Yeah, absolutely check who wrote a comment before relying
| on it
|
| It's luckily rare for people to add wrong comments,
| though (and those who do should be publicly fustigated).
|
| By the way, please never state something as it were the
| truth if you're not sure that it is. Saying "I think" is
| perfectly fine, and might save people days of
| investigation.
| kristiandupont wrote:
| Not the comments I write.
|
| I don't write what the code does or even what "I
| understand the code to do". I explain choices, especially
| ones that the next developer or my future self is likely
| to misunderstand when looking at the code.
| ykonstant wrote:
| >when hen wrote the comment.
|
| I've always said coding is a cottage industry!
| __MatrixMan__ wrote:
| I've got no trouble with that perspective, but wouldn't a
| log message scratch the same itch, plus more?
| PlunderBunny wrote:
| I've never worked in a company where the commit log
| message wasn't just a link/reference to something in a
| bug tracker. I feel like a 'what this block of code does'
| comment is different from 'what is this change, and why
| did I make it' commit message.
| porridgeraisin wrote:
| They meant logging-logs in the code itself:
|
| log.Debugf("Foo is: %#v", ...) //You think: this is
| probably filtering code log.Debugf("Foo without X is:
| %#v", ...)
| 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.
| worik wrote:
| Putting too much emphasis on na,Ed leads to looooong
| names
|
| I've seen 64 character variable names
|
| Names should be mnemonic. Reminding, not describing
| XorNot wrote:
| This is what I tell people: if you're writing a one line
| code comment, write a debug log message instead.
|
| There's vanishingly few cases where this extra logging
| statements will ever be a problem and they can all be
| handled autonomously if they ever are - but it will save
| everyone else a ton of time in deployment.
| kristiandupont wrote:
| You must have extremely busy logs, then? Do you also do
| this with all the code that runs in loops?
| XorNot wrote:
| Do you routinely run production services at debug or
| trace log level?
|
| The point is there's a big difference between "we've got
| a problem, we need to add logging and redeploy to try and
| isolate it" versus "we might have a problem, bump the
| logging level up on that service to see what's going on"
| (which with the right system you can do without even
| restarting).
| __MatrixMan__ wrote:
| I'm not who you're asking, but I do the same
|
| Re: busy, no because I only enable debug logging when I
| need it
|
| Re: loops, I wrote a deduplicating logger, so if there
| are 200 identical messages from within a loop I see:
| {event: "thing happened"} {event: "thing
| happened", duplicates: 100, since:
| "2024-09-11T01:05:00Z", reason: "count reached"}
|
| That is, supposing that it's set to saturate at 100
| events and they all happen fast enough that it doesn't
| reset the count. In this case it'll log another batch of
| 100 on the 201st event.
|
| I think it's important to log the first one immediately,
| just in case you want to alert on that message. It
| wouldn't do to wait for the other 99 before raising the
| alarm.
|
| I wrap my loggers in deduplicators only when I'm about to
| hand them off to a loop. Otherwise it's the normal ones.
| 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.
| readthenotes1 wrote:
| Trouble with comments is that they drift from the code over
| time because most people do not update the comments - -
| based upon my surveying production code bases. If they are
| hidden, it will drift even quicker and become even more
| useless faster
| convolvatron wrote:
| i think in sean's proposed world we'd have metadata about
| that too! the comment in the context it was written in
| would be available, as well as all of the surrounding
| changes that potentially invalidate it. as well as
| potentially a whole discussion thread about what they
| meant when they wrote it, and suggestions about how to
| change it.
| seanmcdirmid wrote:
| ...and the main reason people don't like comments is
| because they clutter up the code that gives them the
| truth of the matter. But yes, if they aren't in your face
| forcing you to look at them rather than the code, then
| they are slightly more likely to not be ignored when the
| code is changed.
|
| It would be nice if they could be like footnotes, or
| boxed out-takes, that could be pushed to side notes. We
| have had the typography, even if it was just markdown
| with a rendered code reading mode.
| shiroiushi wrote:
| This is caused by poor or nonexistent code review
| practices. Reviewers should be ensuring that related
| comments are updated if code functionality is changed.
| yen223 wrote:
| I would urge developers to err on the side of too many
| comments over having too few comments, even if there's a
| risk of them going stale. I can deal with drifting
| comments, but I can't deal with missing comments.
| wtetzner wrote:
| I've found the opposite. Misleading comments can be far
| worse than no comments.
| kmoser wrote:
| You just need a "hide/show comments" extension for your
| IDE. (I would argue that such a feature should already be
| built in.)
| bccdee wrote:
| You don't need to abandon plain text to hide comments.
| Comments are detectable with a regex; an extension to hide
| comments would be trivial to make in most editors. I think
| it's not a common feature because people generally just
| don't want it.
|
| Rich text code would create so many problems, too. You get
| locked into a special editor. You need special version
| control. Grepping becomes difficult. Diffs become
| difficult. You'd need a whole separate ecosystem, and for
| what? We have treesitter; we can already treat code like
| data.
| hughesjj wrote:
| I got some flak at a prior job for saying I had some quibbles
| with clean code (a few years after I had read it), and I'm
| glad this opinion is more popular today. There's so much
| cargo culting hype with "best practices" and style, I hate
| it. Same with how overly dogmatic people were with OOP
| paradigms when it came out (remember using anonymous
| interfaces to pass a function around in java?). Same with the
| functional backlash to that.
|
| It's fun and enlightening to go ham on any particular
| style/framework/philosophy, but actually living by dogma in
| prod gets kinda dangerous and imo is counter to the role of a
| senior+ engineer
| AtlasBarfed wrote:
| The very term "best practice" is such a loaded term. It
| implies:
|
| 1) empirical measurement compared to a large number of
| alternatives ... the empirical measurement or study is
| never mentioned: because they do not exist
|
| 2) the best practice is valid in all measurements and
| criteria of comparison: performance, elegance, simplicity,
| correctness
|
| 3) since there is no data, the reasons for why the practice
| was designated best are rarely even explained
|
| 4) nor are the circumstances or individual or source of
| "best practice" detailed
|
| 5) it will always be the best practice: it is the BEST! It
| CANNOT be improved.
|
| So we have an unsubstantiated, unargued, unsourced, non-
| authoritative, exaggerated declaration in virtually every
| case of "best practice"
| answerheck wrote:
| Copy that. CC has done a lot of harm in some ways.
| appplication wrote:
| Yes I write comments like a maniac. Long doc strings that are
| informally written. It's more important for me to say what I
| need someone else (or future me) to know about a function and
| its context than it is for me to have some beautiful, sterile
| 300-line autogenerated soulless docstrings.
| answerheck wrote:
| Yes, we should all be kinder to both others and to future
| me (you). Do we know who will be maintaining this code?
| Obi-Wan meme: Of course I know him. He's me!
| kazinator wrote:
| I write detailed git commit messages like a maniac.
|
| Git commit messages are better than comments, because they
| tag the specific baseline of code where a decision was
| made, and you can write multiple paragraphs to explain
| something (including all the "why not"), without cluttering
| the program text.
|
| The problem with comments is that they also pertain to a
| revision that existed around the time they were written,
| but they stick around, pointing to newer revisions, perhaps
| falsely. They add clutter. Unless you use a folding editor,
| comments can separate pieces of code so that you see a
| smaller window of the program.
|
| One line of code can be touched by many, many commits. Each
| of those commits should have something to say about that,
| and all that talk cannot possibly be put into a giant,
| ever-growing comment next to that line of code. In regard
| to my previous point, a lot of that talk won't even be
| relevant to the current version of that line!
|
| I've taken the view that the thing I'm developing is a git
| repo, not the source tree.
|
| A source tarball is just something for building and
| deploying, not for development.
|
| If someone wants to understand why something was done, they
| must use the repo, and not a source tarball. If they insist
| on just working with the source snapshot, but ask questions
| that are answerable in the git history, I cannot support
| them.
| worik wrote:
| > I write detailed git commit messages like a maniac
|
| I do not think that helps much, in the general case
|
| > The problem with comments is that they also pertain to
| a revision that existed around the time they were
| written, but they stick around,
|
| Comments do require maintenance. It is part of
| professional practice
| appplication wrote:
| I think this is fine if you have buy in within your team.
| Your concerns around temporarily are valid, though using
| git over comments is a trade off does make understanding
| a particular bit of code an exercise in reading backwards
| until you've captured the entire context. It also implies
| some level of fairly consistent discipline from
| participating members in terms of structuring commits.
|
| That said, git commit messages as a meaningful source of
| information aren't for me, I prefer reading the code as a
| single pane of information. We alleviate concerns about
| doc strings and comments becoming out of sync with the
| code by just reviewing comment salience as part of
| standard code review.
|
| Either way, I think there's no wrong answers, if it works
| for you and your team then that's good.
| cjfd wrote:
| This 'empirical research' is highly doubtful. The first
| question to ask is what the code with summary comments looked
| like. While summary comments can sometimes be helpful, this
| is mostly the case in functions that are relatively long. A
| question that always arises in that case is whether it is a
| good idea to split them instead of commenting.
| 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.
| steveBK123 wrote:
| There's also the comments that tell you why the code does
| something obviously stupid but needs to continue replicating
| this stupid behavior because something else depends on it
| behaving this way.
| paulryanrogers wrote:
| This is the way :mando:
|
| If it's not answering why or at least providing a very
| concise how to very verbose code, then it's just adding noise
| saurik wrote:
| That sounds like "explain[ing] why the code isn't written in
| another way" where the other way is "the way you are right
| now thinking it should be as you read this: the way that
| isn't obviously stupid".
| steveBK123 wrote:
| I'm thinking less in "way the code is written" and more
| "the way the code works".
|
| That is things like cases it doesn't support, or weird
| results in some cases.
|
| One example is a shop I worked many years ago that had a
| function which did time conversion on date times without
| adjusting the date portion. Obviously, objectively, wrong.
|
| However the callers to this function expected this errant
| behavior. Actually changing it to behave correctly would
| require a coordinated change. Putting that comment in place
| prevents a new hire from going "oh this is obviously
| wrong!" and fixing it, causing an outage.
| belorn wrote:
| I find that purpose of comments is to give context to the
| written code. Sometimes the context explains what the code
| does, and more often it explains why, but the best comments
| gives me the reader an insight so that I can have a intuitive
| feeling for what the author are writing.
| anotherevan wrote:
| Cursor cursor = getCursor(); // Cursor.
| erik_seaberg wrote:
| I have seen a linter that requires class User
| { public String getName() { ... } }
|
| to have a doc comment explaining what getName does and also
| what it returns. Before git, they sometimes needed to see who
| wrote it and when.
| pjerem wrote:
| Well, so, does this method return the login name of the
| user ? Or is the "name" field in fact a company convention
| to return firstname and lastname concatenation ? Oh and if
| it's that, what will be the concatenation order ? It
| doesn't seems like it's a parameter but is it configurable
| somewhere ? Is this automatically defined somehow ? Is it
| hardcoded ? Or is there a name field in the database and if
| yes, what does it represent ? Etc ...
| franciscop wrote:
| Within the code you'd have `return this.user.firstName +
| ' ' + this.user.lastName;` or similar, which can explain
| the details of how it works when you look into it.
| DanHulton wrote:
| I'm not super opposed to that, honestly. Doc comments are
| coloured differently from code, and really help you scan
| through a file quickly to find the next function. It
| honestly doesn't take more than a couple seconds to write,
| and (I find) it really helps readability enough to be worth
| it.
| wrwatson wrote:
| I think of comments as an apology to the engineer reading the
| code.
|
| I'm apologising because the code isn't obvious, or the language
| not sufficiently expressive, or the good-idea-at-the-time no
| longer is. Ideally I wouldn't need to write many comments, but
| I often find myself sorry things are not simpler.
| atoav wrote:
| In the end a comment should be like a shortcut that allows
| people to understand your code faster or a reminder why
| certain choices were made.
|
| You are right in spirit to say sorry when the code cannot be
| self-explainatory, but consider that sometimes even if the
| code is self explainatory, comments can help your reader to
| see the grand picture faster or to avoid interpersonal
| ambiguity by allowing you to use two different ways of
| phrasing a thing.
| incontrol wrote:
| When I feel the need to add a comment, I convert that piece of
| content into the named function.
| kaoD wrote:
| So how do you document what is not in the code?
| tubthumper8 wrote:
| Obviously in the function name! void vend
| orReturnsDataInInvalidFormatAndButShouldBeResolvedByVendorO
| penTicketXYZ_123ExpectedResolutionQ42024(String input) {}
|
| /s
| kwhitefoot wrote:
| > writes comments that explain why the code isn't written in
| another way."
|
| Exactly! I have written code that required comments five times
| as long as the code itself to defend the code against well
| meaning refactoring by people who did not understand the code,
| the domain, or the care needed to handle large dynamic ranges.
|
| I have also written substantial functions with no comments at
| all because it was possible and practical to name the function
| and all the variables so that the meaning was clear.
| yxhuvud wrote:
| I've also written that kind of comments, and then promptly
| had it refactored by people not reading comments.
| klyrs wrote:
| It's true! If you come across a well-documented and complex
| piece of code, it's always easier to delete it all and
| write a simpler (and less correct) replacement than reading
| all of that code and documentation. And since your
| replacement is simpler, you're free to delete the
| inapplicable documentation that you saved so much time not
| reading!
|
| If you didn't back that documentation up with some tests to
| reflect the necessity of that complexity, this is an
| avoidable tragedy. But if the junior then comes in and
| deletes your tests because they don't pass, that's a
| firin'.
| cesaref wrote:
| Junior programmers tend to either document nothing, or document
| everything. With experience you realise that you just want to
| document the unusual stuff, and as you get more experienced,
| you realise there is less and less unusual stuff, so the amount
| of comments drop down.
|
| So, less comments wins out, but faced with a code base without
| comments you have to inspect it to tell the difference between
| a beautifully crafted piece of brilliance or a totally flaky
| codebase written by a bunch of newbie hacks.
| lawn wrote:
| > and as you get more experienced, you realise there is less
| and less unusual stuff, so the amount of comments drop down.
|
| This is a common experience when I use a new language or
| framework. At the start I comment a lot of things because I
| think it's useful for future me, but as I learn more I
| realize that many of the comments are redundant so I end up
| removing them.
| andoando wrote:
| You have to consider who the comments are for. Senior
| engineers comments are more useful for senior engineers, but
| the junior comments will be more useful for junior engineers.
| seanw444 wrote:
| I don't know. Senior engineers may understand the point of
| the code already, and "why it's not written a different
| way." The comment could be explaining to the less-
| experienced devs why they shouldn't waste time on another
| intuitive-at-first-glance approach.
| david-gpu wrote:
| _> A senior engineer writes comments that explain why the code
| isn 't written in another way_
|
| I suggest providing that sort of high-level decision
| information in a separate design document. This sort of
| documentation is written before the code and is
| presented/discussed with management and peers.
|
| That is how it was done at a couple of companies I worked at
| and it was very effective. Naturally, this was done at the
| feature level, not on a function to function basis.
| solidninja wrote:
| That still needs discipline though - or you end up with N
| half-finished Confluence pages describing the intention
| behind the design, all of which are now out of date (and
| naturally in completely different places). The best way I've
| seen to keep track of changing things is to have the design
| linked to the ticket somehow (and if it's a link, then that
| needs to be a permalink to something that will not go away in
| a year's time).
| anhner wrote:
| I understood that to mean "I've tried doing it x way and it
| didn't work because y." rather than the functional part. At
| that point, why not keep the documentation together with the
| code?
| bccdee wrote:
| Then you end up with a design document that corresponds to
| the code as it existed conceptually before v1 of that code
| was even written. By the time v1 is written, the design doc
| will be slightly out of date; by the time the code reaches
| v3, the document is more than 2 versions out of date.
|
| The nice thing about comments is that they're _in_ the code.
| You can 't update the code without at least looking at them;
| that's more visibilty than you'll get from anything else.
| david-gpu wrote:
| Design documents were updated as the code changed,
| obviously. Changing the code without updating the documents
| would not pass code review if somebody was shortsighted
| enough to try.
| zo1 wrote:
| I really have to push back against this "design document"
| stuff. Unless you're writing some sort of uber-complicated,
| mission-guidance-systems-level code with multiple standards
| and audit compliance and and and, then you don't this.
|
| Alternatively, if your org or reach for this feature is so
| large that you need to communicate and decide its internals
| with a lot of people and as such require something like a
| design document, then you've already failed and you have way
| too-many cooks in your kitchen. Design by committee is always
| doomed to failure.
|
| Thirdly... if you need a design document to communicate your
| feature to "management" then that means you don't have
| autonomy to design this feature as an expert, and again, you
| have too many "fingers" in your pie.
|
| Does this mean you should go into a basement and design your
| feature like a hermit? No, but a design document shouldn't be
| your answer, it should be a better team and process around
| you, as well as a clear business specification.
| david-gpu wrote:
| We did and it worked great.
|
| The process led to not only better designs, but also better
| visibility for all stakeholders, from technical leads to
| individual contributors.
|
| I'm talking about products that shipped on billions of
| devices, products that you have most certainly used. It
| worked.
| MyFirstSass wrote:
| True! Also i sometimes also do "yes this looks weird, but it's
| because : somebugtracker.issue"
| 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 mean. (And I'm
| not a professional programmer, so my coworkers don't write
| code.)
|
| To me, the suggestion seems so incredibly bad that it leaves
| me wondering about the headspace of someone who would suggest
| that. Is it somehow less bad than it seems?
| herpdyderp wrote:
| Yes. I currently work in a codebase where the previous tech
| lead did that and promoted such behavior (among many other
| insanity-inducing practices).
| mgsouth wrote:
| There are many, many developers who are, deep in their hearts,
| "programmers"--someone who creates a plan of action, a program,
| for very complex machines to follow. They are skilled at
| discerning The Right Way to solve a problem. Actually, THE
| Right Way. And since they are Programmers, the Right Way is to
| find the Best Way to tell the computer what to do. Computers
| are completely oblivious to comments, so they aren't The Best
| Way. Comments are ambiguous, so they can't be THE Right Way.
| Computers parse identifiers, so a good variable name is telling
| the computer _something_ at least, and so is vastly preferrable
| to comments. If there's a mismatch between comment and code,
| the code is Reality so the comment must be wrong, and is thus
| misleading and worse than useless.
|
| In reality, of course, software development is about getting
| large groups of people in-sync as to problem, solution, and
| implementation. That takes lots and lots of communication.
| Ambiguous, messy people-to-people stuff, without The Right
| Solution to contents or wording. Because there's a bias towards
| thinking of the Program as Reality, it never occurs to such
| developers that an identifier can become just as outdated or
| wrong as a comment, and in fact it is easier to correct a
| comment than to globally rename identifiers, or that a 20-word
| comment carries vastly more information and nuance than a
| 20-character function name, or that trying to shoehorn
| information important to developers into a language used to
| tell _computers_ how to function is worse than trying to drop
| assembly language into a SQL query.
| Wowfunhappy wrote:
| > Computers parse identifiers, so a good variable name is
| telling the computer _something_ at least, and so is vastly
| preferrable to comments.
|
| I realize you're trying to explain a way of thinking that you
| don't actually share--but this doesn't make sense to me
| either.
|
| Computers parse identifiers in only the simplest sense--they
| care if two identifiers are identical to each other or
| different. So, any identifier longer than one or two
| characters is in some sense a comment, because everything
| longer the minimum necessary to make the identifier unique is
| ignored. They're literally stripped from the output if you
| don't retain debug symbols or use a minifier (depending on
| the type of language).
| Pinus wrote:
| In my experinece,
| veryLongVariableNamesThatContainADetailedExplanation are almost
| always a sign that someone didn't quite know what they were
| doing.
|
| Unfortunately, short names do _not_ indicate that someone _did_
| know what they were doing! =)
| 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.
| hughesjj wrote:
| It would be super cool if you could provide a list of line
| ranges for comments. Like "this comment covers lines 12-14".
|
| I suppose if you make the refer nces fancy enough you wind up
| reinventing rst
| RandallBrown wrote:
| This is actually really easy to do in most languages by
| wrapping the code you want to comment in a function.
| func uglyHackForCombiningTwoThings() { // Do
| whatever ugly thing you want to do }
| GuB-42 wrote:
| You don't need a function, a simple {} block is enough if
| the language supports it. Some languages (ex: Python) don't
| have that though, you may need a function, or some other
| construct (ex: if true) in this case.
| Denzel wrote:
| In his specific example, a comment is not the best solution.
| You can create self-documenting code easily with an interface
| and an implementation, also commonly referred to as the
| strategy pattern.
|
| Interface expresses "what the function does" while the
| implementation expresses "how it's done with what tradeoffs".
|
| Bonus, in the future, if performance ever does become a
| problem, you swap in the new optimized implementation behind
| the existing interface.
| 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.
| matt_lee wrote:
| > Why not "why not" comments? Not why "not comments"
|
| I nearly exploded trying to grok this
| giraffe_lady wrote:
| u can tell this dude loves algebra
| philipwhiuk wrote:
| Personally I think you're better off putting 'not comments' in
| git commit information. Git commit comments are like normal
| comments except they don't get detached from the code.
| jakub_g wrote:
| I believe this can work in slow paced opensource projects which
| do squash-merges (one PR = one commit), every commit is green
| and beautiful and well described with properly formatted
| message.
|
| I worked on such project in my first job and I cared a lot
| about my commit messages, and changelogs.
|
| On the other hand, in fast paced corporate development I barely
| ever see someone make commit messages like this. Even PR titles
| often leave a lot to be desired.
| keybored wrote:
| Squash merging is a practice I mostly see recommended (I
| mean: mandated) from those corporate environments which churn
| out code like a paper mill trying to put the Amazon out of
| existence. OSS projects that _can_ take their time with nice
| commit messages--which even review them, not just the code--
| don't have to limit themselves like that.
| jakub_g wrote:
| Apart from what/why/why not: Something I started doing recently
| is to put URLs in the comments:
|
| - URL of documentation for a complex feature
|
| - URL with a dashboard with telemetry
|
| - URL of a monitor which checks if the given feature, CI job,
| GitHub action etc. works correctly.
|
| In a big project, figuring this stuff out is not trivial,
| requires a lot of searching with proper search terms and/or
| asking the proper knowledgeable person.
|
| I find it weird that code is often so detached from everything
| non-code.
| jesse__ wrote:
| I ascribe to the notion that 'comments are apologies' (to my
| future self).
|
| If a piece of code is weird, or slow, or you'd say "yeah, it's
| kinda janky" when describing to somebody, I usually write a
| comment about it. Especially if I've changed it before; to
| document some case that didn't work, or I fixed, or whatever.
|
| When you operate on this basis, superfluous comments just melt
| away, and you typically end up documenting 'why' only when it's
| really necessary.
|
| Try it out in your own codebase for a month and see how it feels
| :)
| gregmac wrote:
| > 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. Virtually all "self-documenting" codebases
| add documentation through the addition of identifiers.
|
| Identifiers can go a _long_ way, but not _all_ the way. I
| personally am a fan of requiring documentation on any public
| methods or variables/fields/parameters (using jsdocs/xmldoc/etc).
| Having a good name for the method is important, but having to
| write a quick blurb about what it does helps to make it even
| clearer, and more importantly, points out obvious flaws:
|
| * Often even the first sentence will cause you to realize there's
| a better name for the method
|
| * If you start using "and" in the description, it is a good
| indication that the method does too much and can be broken down
| in a more logical way
|
| People often think properties are so clear they don't need docs,
| then write things like: /** The API key */
| string ApiKey;
|
| But there's so much missing: where does this key come from? Is
| this only internal or is it passed from/to external systems? Is
| this required, and can it be null or empty? Is there a maximum?
| What happens if a bad value (whatever that is) is used? Is there
| a spot in code or other docs where I could read more (or all
| these questions are already answered)?
|
| This is stuff that as the original author of the code you know
| and can write in a minute or two, but as a newcomer -- whether
| modifying it, using it, or just parachuted in to fix a bug years
| later -- could take _hours_ to figure out.
| yodsanklai wrote:
| This seems a bit like a strawman argument. I don't think anybody
| say that we should never use comments.
|
| The problem with comments is that they can become stale, and it's
| often possible to self-document or write simpler code that causes
| less surprise. But of course, it's totally fine to put comments.
|
| And I think comments should be mandatory for interfaces
| functions/types unless their behavior is obvious. I don't want to
| read the code to understand what a function does, or what
| invariant a class maintains. And if it's too complex to document
| in a few lines, probably this isn't the right interface. But
| apparently, this isn't obvious for everybody. In my company, most
| of the code isn't documented.
| boerseth wrote:
| >The negative comment tells me that I knew this was slow code,
| looked into the alternatives, and decided against optimizing.
|
| I admire the honesty, but will continue to phrase these _" why
| not"_ comments as insincere TODOs.
| anotherevan wrote:
| I think the favourite type of comment I've ever left in my code
| follows this template: DEAR MAINTAINER:
| This code is the way it is because of <reasons go here>.
| Once you are done trying to 'fix' this, and have realised what a
| terrible mistake that was, please increment the counter
| as a warning to the next person:
| total_hours_wasted_here = n
|
| I'm not the original author, but have gratefully used it once or
| twice, and been amused when there was a single line commit
| incrementing the counter.
| tombert wrote:
| I wish I had had this years ago.
|
| I one time wrote this fairly elaborate SQL generation thing
| that required pretty liberal use of recursion in order to
| fulfill all the requirements. It ended up being a lot of mutual
| recursion and the code was admittedly kind of messy but it was
| a necessary evil to do everything asked of me.
|
| A more senior engineer ended up taking over the codebase,
| "fixed" all my code to be this iterative thing, made a point to
| try and lecture me about why recursion is bad in an email, only
| for his code to not actually do everything required and him
| reinventing effectively everything I did with recursion.
|
| In fairness, he did actually apologize to me for some of the
| comments he made, but if I had thought about putting this
| comment on the top maybe we could have avoided the whole thing.
| spencerchubb wrote:
| My team comments way too much. I constantly see stuff like this
|
| def fetch_data(comment_id): Args: -
| comment_id: The id of the comment to fetch. Returns:
| The comment data
|
| # Fetch comment data
|
| data = fetchCommentData()
| Minor49er wrote:
| Mine do this as well, but in PHP. They adopted docblocks over a
| decade ago and never defined any best practices or used any
| tools to check them, so comments don't even match the code half
| of the time. We're on PHP 8 now which can enforce types in the
| code itself but still have to include docblock types because
| that's how it has always been done, so the problem persists.
| It's maddening
| zwnow wrote:
| Comments tend to get outdated quickly as your app grows. If you
| are not careful with your phrasing you might even introduce
| misinformation into your app. I'd rather read the code instead of
| comments.
| jimmaswell wrote:
| I love when a docstring saves me from reading code. "Takes
| parameter x which should be in state s, has side effect e,
| returns j, throws exception if .." Seeing that in my IDE popup
| and moving on with all the info I need is so satisfying
| compared to having to waste my time on an unwanted spelunk.
| It's also impossible to embed all this in a name that isn't a
| camelcase paragraph.
| zwnow wrote:
| I can imagine that this is helpful to some people, but when
| coding I ignore comments usually. Good docs and code is all I
| need.
| at_a_remove wrote:
| Although I had started programming when I was nine, in high
| school I was fortunate enough to have a computer science teacher
| with a PhD in the field. Among one of the habits drilled into me
| was extensive commenting.
|
| Every function (or procedure) starts with a comment block. It
| first talks about the what and why. Then, a line for the inputs
| and another for the outputs. Next -- and this is done closer to
| the end of the writing -- I describe what it calls and what it is
| called by. The comment block optionally finishes with room for
| improvement.
|
| The function itself probably has other comments. Usually for
| anything which is not _blindingly obvious_. Because I write code
| like a caveman, wherein only one thing happens on one line, most
| everything is quite clear. If there 's anything weird or magical
| that has to happen, it gets a comment.
|
| Elegance and cleverness is reserved for data structures,
| algorithms, and so on, rather than doing a lot of stuff in as few
| lines as possible. I do this for Future Me, who might be having a
| bad day, or for anyone who wants to adapt my code to something
| else.
|
| One of the last steps in a finished program is going through and
| making sure that my comments match my code. I am a very boring
| kind of programmer.
| kqr wrote:
| Another big one I wish I saw more often is "these are the
| circumstances under which this assumption was made and here are
| the steps you can take to check if those circumstances have
| meaningfully changed."
|
| In other words, the comment allows the author to reach into the
| future and co-debug with the reader, even if the author is no
| longer there.
| ktosobcy wrote:
| I somewhat dislike the notion of "self-explanatory code"
| (especially if someone has tendency to be "smart")... optimise
| for reading and add comments!
| analog31 wrote:
| One issue with comments is that an engineer who struggles to
| write clearly will also struggle to write clear comments. And
| clear code. But at least the code can be deciphered by reverse
| engineering it, stepping through it, or in some cases rewriting
| it. For me, at least the comments are worth reading before trying
| to figure out what someone's code does, to get me into the
| ballpark.
|
| I often add comments to code as I decipher it, then remove them
| again when I figure things out.
| geraldwhen wrote:
| An engineer who struggles to write clearly is one I would hope
| not to hire. Programming is first and foremost a problem
| discovery job, then a writing job, then math and logic.
|
| No matter how efficient or eloquent, if you solve the wrong
| problem, you're doing no one any good.
|
| Solve the right problem efficiently, but in a way no others can
| understand, and you'll flounder in a team. You will also never
| be able to collaborate or make larger work move faster.
|
| Correct problem, clear writing, then logic.
| analog31 wrote:
| I definitely agree, but still, a lot of people are told "you
| will never use your math or writing after college." It may
| also be that they perceive themselves to be judged by how
| much code they can sling, and not the quality of their
| writing. And in a large enough department, the work that
| depends on math ends up being given to the one or two "math
| people." I'm one of those.
|
| But I suspect that there's a relationship: If their writing
| is hard to read, their code will be hard to read.
| veltas wrote:
| Why not question-mark?
| Timwi wrote:
| This is just a special case of a broader, more general advice
| that I follow:
|
| Comment on whatever would be surprising when you read the code.
|
| When I write code, a voice in the back of my head constantly asks
| "will I understand this code later?". (People who just
| instinctively answer 'yes' every time are arrogant and often
| wrong.) Whenever the answer is 'not sure', the next obvious
| question is "why not?". Answering _that_ question leads you
| directly to what you need to write in your comment.
|
| Sometimes the answer is "because the reader of the code might
| wonder why I didn't write it another way", and that's the special
| case this article covers. But sometimes the answer is "because
| it's not obvious how it works or why it's correct" and that
| clearly requires a different type of comment.
| perlgeek wrote:
| As an addition, if you first try to write the code one way, and
| then it doesn't work and you need a second approach, that's a
| really good indication that you want _some_ kind of comment
| there. You were surprised while writing it, so if you 'll
| forget that surprise in a year, you'll be surprised by reading
| it too.
| albrewer wrote:
| > "will I understand this code later?"
|
| My driving principle in the same vein is "where do I have to
| look when/if this doesn't behave as expected?" - if the answer
| is not in the docs (wiki -> package/module -> file -> class ->
| function / method) or is otherwise > 10 lines away, it gets an
| inline comment (or the docs are updated). Usually this happens
| when chopping up strings or during intermediate navigation
| steps over an odd data structure.
| narag wrote:
| I comment everything that I think would be useful for me when
| revisiting the code a year later. Usually "why" and "why not".
| Sometimes a short "what" when the code is complex and it's nice
| to see the sequence more clearly.
|
| What's not so useful: mandatory comments. A public API should be
| thoroughly documented, but some shops insist on writing comments
| for every function in the code, even private ones and even if its
| purpose is so obvious that the comment just rephrases its name.
| This practice is not only a waste of time, but also insensitizes
| you about comments and teach you to ignore them.
|
| Other wasteful comments are added by some tools. I hate the one
| that marks every loop wiht a //for or //try comment.
| cjfd wrote:
| Yes, completely agree. Also, too many comments make it
| difficult to see what is in a class/function. If the comments
| make a class/function that would otherwise fit on one screen no
| longer fit on one screen there is a readability cost to this.
| exe34 wrote:
| I wish they would put the comments before the function name
| in python, as otherwise the useful code is separated by
| useless verbiage. I also wish comments would include examples
| of the shape and dtype of inputs and outputs.
| BeetleB wrote:
| Collapsing/hiding comments should be a required feature in
| editors.
|
| In Leo[1], you can make nodes out of them and just hide them.
| If Emacs weren't so good, I'd be using Leo. Similar power
| when it comes to extensibility, but extended via Python, not
| elisp.
|
| [1] https://leo-editor.github.io/leo-editor/
| gwervc wrote:
| > Usually "why" and "why not"
|
| Related anecdote: yesterday I was on a code portion of a
| personal project with a "Is this really useful?" comment on a
| line that seemed it could easily be removed. I tried to use the
| newer and cleaner class instead and the particular old way was
| indeed needed. So I appended a "=> yes!" to the existing
| comment as well. I'm glad my former self documented the
| interrogation.
|
| At work, especially on bugfix, I often write a one or two lines
| comment with the ticket issue number over a non-obvious change.
| danadam wrote:
| > So I appended a "=> yes!" to the existing comment as well.
|
| You will read it in 3 months and cry in despair "But why, my
| past self, why is it needed?!" :-)
| zizee wrote:
| Hopefully they recorded it in their commit log.
| gwervc wrote:
| Actually (I wanted to keep the story short), I added a
| new comment on the line before stating that the other way
| isn't working.
| Cthulhu_ wrote:
| For some reason a lot of syntax highlighting color schemes de-
| emphasize comments, making them low contrast, which is probably
| because a lot of mandatory / generated comments are low
| information. Get rid of mandatory and generated comments, and
| change your color scheme to make them a bright neon colour
| instead (on a dark theme) to draw the attention, because IF
| something is commented then it's important.
| dizhn wrote:
| I disagree with this. Comments are important but not every
| time you're in that part of the code. You might already know
| from just the code what's going on, or have already checked
| out the comments. There's no value to them always being
| emphasized. That would be like reading all NPC dialogs every
| time in an RPG.
| bluGill wrote:
| If there is a comment is should be important enough to read
| it every single time you are near that area of code even if
| looking for something else in the file! They should be a
| reminder of something important and not obvious in the code
| - otherwise I'll just read the code.
|
| Note that I distinguish comments from API documentation
| even though they are often both in the same code and use
| the same comment syntax.
| qrobit wrote:
| If there is something really important worth rereading
| over and over again, put <<NOTE: >> before it and let
| your editor highlight it for readers of your code
| Attrecomet wrote:
| > Other wasteful comments are added by some tools. I hate the
| one that marks every loop wiht a //for or //try comment.
|
| Oh god, that's horrible, what kind of tool does that?!
| narag wrote:
| I don't know, the guy is no longer around. Maybe some code-
| completion tool (write "for" and it completes the syntax)
| because it's all over the place.
| bbarnett wrote:
| Eventually, we find out he wrote it all manually.
| skipkey wrote:
| It was pretty common say 25 years ago when you would be
| developing in a terminal. When you were limited in the number
| of lines displayed, it sometimes made it easier to follow the
| code when functions and control structures were large.
|
| I know I had coworkers using brief configured to do that.
| harry_ord wrote:
| I find the why and what are so useful. If I know why what the
| code is aiming to achieve, it makes rewriting it or fixing a
| bug much easier
| gspencley wrote:
| > I comment everything that I think would be useful for me when
| revisiting the code a year later.
|
| Do you code solo or do you work with a team? If so, how large
| is the largest team you've worked with?
|
| I used to be a dogmatic "all comments are code smells" person
| and, to a large degree I still am. But working on a very (and I
| mean VERY) large code-base that is actively developed and
| maintained by hundreds of other software developers, I have
| relaxed my position slightly into the "if you need to do
| something weird, explain why" ... because a large legacy system
| that lives in a business environment of tight deadlines means
| that there are often weird things that need to be done to keep
| things moving at a pace that the business is willing to pay
| for.
|
| Anyway, one of the many reasons that I argue AGAINST code
| comments is that the comments become part of the code and
| therefore require maintenance. But few people read comments
| unless they are stuck trying to understand something. This
| "psychological invisibility" is even enforced by the fact that
| most code editors will grey out comments in order to make them
| less distracting.
|
| And therefore, comments can easily become outdated.
|
| So I'm curious about your situation. Since you say that you
| like to give yourself useful context for "future you", what
| context does this process serve? Do you find it useful when
| working on a shared codebase with lots of other developers? Or
| is it something that only works well when there are few
| developers touching the code?
| mplewis wrote:
| Comments that I leave for myself help remind future-me why I
| did something that otherwise looks confusing.
| pwdisswordfishz wrote:
| > Why not "why not" comments? Not why "not comments"
|
| Or you know, you could have just used a hyphen instead of
| clickbaiting.
| dekervin wrote:
| I am working on the abandonned idea of a rapgenius for code. I
| think it still is a useful idea for the open source world. You
| can join the HN learn discord [1] if you want, so I can keep you
| posted.
|
| [1] https://discord.gg/ks4yfPgbyn
| agentultra wrote:
| May also sometimes, when designing algorithms, be useful for
| documenting pre- and post-conditions and invariants in procedural
| languages that lack embedding such specifications. You can't
| really reason about these things in the language itself and end
| up having to use something else (predicate calculus usually) but
| it's nice to at least have an indicator, as tfa suggests! What
| code _doesn 't_ do is important!
| pdpi wrote:
| I find myself following only two or three different patterns in
| comments:
|
| There's often a fairly small kernel of very dense code that
| abstracts away a bunch of complexity. That code tends to have
| well north of a 1:1 comment to code ratio, discussing invariants,
| expectations, which corner cases need special handling and which
| ones are solved through the overall structure, etc.
|
| Then there's a bunch of code that build on that kernel, that is
| as close to purely declarative as possible, and aims for that
| "self-documenting code that requires no comments" ideal.
|
| Finally, there's the business logic-y code that just can't be
| meaningfully abstracted and is sometimes non-obvious. Comments
| here are much more erratic and often point at JIRA tickets, or
| other such things.
| aurelien wrote:
| BBBbbbbeeeeccccaaausssseeeeEEEE!!!!
| yawnxyz wrote:
| in the age of AI and Cursor, I make my function name as
| expressive as I can, and I make sure to add a couple of lines of
| comments, either generated or manual.
|
| It makes it way easier to send these into Claude (it seems, at
| least). I hope they introduce a semantic/vibes search too as I
| can never remember what I name my classes and functions...
| k__ wrote:
| Would be cool if literate programming caught on.
|
| It seems only to be a thing with Jupyter notebooks, and even
| there it mostly describes the results and not the code.
| mark-r wrote:
| I once wrote a bubble sort into production code, because the
| total number of elements to sort rarely exceeded 4 and it was
| what I could do off the top of my head. I don't remember if I
| left a comment explaining the reasoning, but I think I did. A
| year later a new feature invalidated my assumption about the
| number of elements and the sort was way too slow. I'm sure the
| person who inherited that code cursed me a few times.
| flerchin wrote:
| Comments and docs are lies that I dearly love. I want and need
| them, but I never forget that they're, at best, helpful lies. The
| code does exactly what's written, the comments adhere more or
| less, sometimes.
| tombert wrote:
| My rule of thumb has been "comment stuff that isn't the naive
| solution", basically anything that would make someone think "wtf
| is this" the first time they read it.
|
| My biggest headache right now has been getting high-throughput
| with SQL and as such I've had to do a lot of non-obvious things
| with batching and non-blocking IO in Java to get the performance
| I really need, and as such a of the "obvious" solutions don't
| work (at least with a reasonable amount of memory). Consequently
| I've been pretty liberally commenting large segments of my code
| so that someone doesn't come in and start bitching about how
| "bad" my code is [1], "fix" it, and then make everything worse by
| rewriting it in a more naive way that ends up not fulfilling the
| requirements.
|
| [1] I have since stopped doing this, but I'm certainly guilty of
| doing this in the past.
| W0lf wrote:
| My rule of thumb for code comments is to comment what's not in
| the code.
| kazinator wrote:
| Most comments belong in the git log message. That's where you
| want to discuss the "why not". You have all the space you need in
| order to do that, without cluttering the code. The log message
| will accurately pertain to the change made at that time.
|
| When commits are rebased, the log message must be revisited and
| revised. Changes can disappear on rebasing; e.g. when a change
| goes into a baseline in which someone else made some of the exact
| same changes in an earlier commit, so that the delta to the new
| parent is a smaller patch. In my experience, commit messages stay
| relevant under most rebasing.
|
| Comments are (largely) an obsolete version of version control log
| messages.
|
| In the 1980s, there was a transitional practice: write log
| messages, but interpolate them into the checked out code with the
| RCS $Log$ thing. This was horrible; it practically begs for merge
| conflicts. It was understandable why; version control systems
| were not ubiquitous, let alone decentralized. You were not
| getting anyone's RCS ",v" file or whatever.
|
| Today, we would be a few decades past all that now. No $Log$ and
| few comments.
|
| Mainly, the comments that make sense today are ones which drive
| automatic API documentation. It would not be reasonable to
| reconstruct that out of the git history. These API comments must
| be carefully structured so the documentation system can parse
| them, and must be rigorously maintained up-to-date when the API
| changes.
| thehappyfellow wrote:
| How am I supposed to be aware of a commit message specifying
| the "why not" when reading the code later down the line?
|
| I could easily imagine somebody refactoring code to an
| obviously better version, finding out it doesn't work for
| subtle reasons, running got blame and cursing the person who
| left that information in a commit message instead of a comment.
| deodar wrote:
| There is no hope for the software industry to mature if we cannot
| agree on some basic coding practices. Like the judicious use of
| comments to improve maintainability.
| worik wrote:
| I have had the experience this year of working on a system with
| 150k lines of C ant 150k of Typescript. The gentleman who wrote
| it in 36 months quit and here I am.
|
| He did not believe in comments, much. I think he thought he was
| commenting the hard stuff, meh, I am unsure.
|
| It has led me into strong opinions.
|
| * Document every function. The function should make clear what
| the preconditions, preconditions, and the purpose are
|
| * Docunebnt every file/code unit. Why it exists
|
| * Document important loops like functions
|
| * Document the easy stuff. It is not easy if unfamiliar
|
| * Review the comments when working on code
|
| This would have saved my company about thirty percent of my time.
|
| The compiler does not verify comments, like it does code, so it
| is a burden. Bad programmers get another opportunity to sow
| chaos, I know. But one of the main purposes of code is
| communication with following humans, as well as controlling
| machines
|
| Careful and thoughtful comments are a professional obligation IMO
| obelos wrote:
| Do you really need to comment to yourself or anyone else that you
| did a thing the less efficient way because it was simpler? I
| guess I"m not seeing the use. When later you've perturbed the
| criteria that caused that function's inefficiency to be
| immaterial to overall performance needs and it suddenly becomes
| material, profiling is going to reveal the low-hanging fruit
| faster than digging through the code for a "this could be faster
| a different way" comments.
| wwarner wrote:
| I would call this "defensive coding", analogous to defensive
| driving. And comments that talk about something that isn't there
| is way too defensive, kind of like the excessive braking and
| overly polite waving that can make 4 way stops so confusing.
| Write your code clearly, keep your functions wholly visible
| without scrolling, keep the comments to a minimum, and put the
| ideas that can't be expressed as code in a README.
___________________________________________________________________
(page generated 2024-09-11 23:01 UTC)