[HN Gopher] Reducing technical debt by valuing comments as much ...
       ___________________________________________________________________
        
       Reducing technical debt by valuing comments as much as code
        
       Author : ternaryoperator
       Score  : 55 points
       Date   : 2023-01-31 18:41 UTC (4 hours ago)
        
 (HTM) web link (blogs.oracle.com)
 (TXT) w3m dump (blogs.oracle.com)
        
       | ternaryoperator wrote:
       | The link at the end of the article to the JVM written in Go is a
       | cool project. The GH project is at
       | https://github.com/platypusguy/jacobin
        
       | swatcoder wrote:
       | Comments are _critical_ to long term project quality and
       | consistency, but they 're always going to rot until tooling
       | starts taking them seriously.
       | 
       | For instance, it's great that code reviews have become standard
       | practice at most organizations and for many projects, but the
       | tooling for those reviews almost always rely on showing the few
       | lines above and below a code diff. The reviewer has no convenient
       | way of seeing how the changed code may conflict with any
       | applicable comments unless the comments happen to be within those
       | few nearby lines or the diff happens to include comment changes.
       | Even then, the big picture is out of view and rot is still likely
       | to seep in.
       | 
       | It would be nice if incoming developer-support AI could start
       | tackling this, by surfacing impacted comments and even "linting"
       | them for applicability and accuracy.
        
         | alexisread wrote:
         | Even better if the language supports scoping comments to
         | particular code blocks, and comments can be made in
         | markdown/mermaid (or equivalent) so you can diagram, link and
         | TODO comments.
         | 
         | Documentation tooling should be able to make a good job of
         | constructing a class/function DAG with scoped commentary. This
         | is kind of a reversal of Literal documentation, but I suspect
         | it may be more maintainable by teams.
         | 
         | Literal docs only seem to go in one direction, that is
         | documentation->code, not the other way around. This I guess is
         | more in-line with scientific hypotheses. Literal tests may be
         | even more tricky as TDD doesn't gel well with Literal
         | hypotheses.
         | 
         | I guess a Doc-driven dev process would be a novel approach
         | here, and probably more usable than AI-supported systems.
         | Copilot has been quite divisive on it's effectiveness.
         | 
         | DDD in that every eg. Class requires a comment and a test even
         | if they are blank, to force at least a thought about them.
         | Having a code manifest at the root of a repo can also be used
         | to configure the envs the code runs in, and the integration
         | tests that it needs to do both local and in-place.
         | 
         | Lastly, as mentioned elsewhere, logs are comments as well, and
         | again would be well to be scoped in the language.
        
         | cma wrote:
         | Mayhe something like chatGPT could be fed diffs of a change and
         | warn about comment rot and recommend fixes (once it has a much
         | bigger context window).
        
       | majikandy wrote:
       | I love seeing comments in the code as they are usually the best
       | entertainment I get all day. Especially when the code below it
       | pretty much doesn't do what it says anymore.
        
       | exabrial wrote:
       | Unpopular opinion, but in the words of Linus, I have my asbestos
       | underwear on so flame away:
       | 
       | * Comments are excuses
       | 
       | * They're used to validate the existence of crappy code
       | 
       | * They do nothing for you in production
       | 
       | Instead:
       | 
       | * we commit to writing log messages... which are sort of like
       | comments, but they work in production
        
         | eatsyourtacos wrote:
         | >Comments are excuses
         | 
         | What the hell is that supposed to even mean? Then writing log
         | messages are excuses too.
        
         | weatherlight wrote:
         | Not unpopular at all. This is totally sane. I wish more
         | companies cared about good coding practices, code quality, and
         | development life cycle. Things like comments made more sense in
         | an era when there was no version control, no conventions around
         | code style, no testing, etc.
        
           | eatsyourtacos wrote:
           | Hey everyone look, we have version control! That means there
           | is no reason to explain anything!
           | 
           | Version control, code style conventions, and testing have
           | _nothing_ to do with explaining how something works or
           | writing about potential pitfalls of this function if some
           | other core logic were to change etc.
           | 
           | Absolutely baffling you guys are arguing for never writing
           | comments.
        
             | weatherlight wrote:
             | no one is arguing that.
             | 
             | Comments are for things that are __impossible__ to tell
             | from the code and the code alone.
             | 
             | Comments are subjective, code isn't.
             | 
             | 90% of the companies I've worked at have had commits linked
             | to actual tickets in a ticketing system. if i really need
             | to understand what was going on, holistically, i could just
             | git blame and go there. i look at tests, I look at the
             | discussion around the code between the person who reviewed
             | the PR and the person who raised the PR. Too often people
             | use comment incorrectly or noisily.
             | 
             | No one is saying you shouldn't write comments. People are
             | saying there are way better practices out there and you
             | should really ask your self, why you are writing a comment
             | to begin with and is there a better way to capture what it
             | is your are trying to do so product managers, developers,
             | engineering managers, QA people understand what the intent
             | of that commit was.
        
         | dbrueck wrote:
         | Code captures only a portion of the thinking that went into the
         | software's design. If you don't preserve the rest of that
         | thinking elsewhere, you're forcing people to recreate /
         | rediscover it later - and probably the most common way to do
         | that is to throw away the code and rewrite it.
         | 
         | So-called "level of intent" comments as well as comments
         | highlighting tradeoffs, gotchas, flaws, limits, exceptions,
         | assumptions, and so on, are incredibly valuable if you preserve
         | them alongside the code. Comments explaining why this function
         | exists and what it's for can help you quickly come up to speed
         | on a new code base - this is especially helpful when it comes
         | to handing off code to a new owner or expanding the team of
         | owners. The following code may or may not be well written (who
         | can say??) but it's not exactly inviting new contributors:
         | https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/moti...
         | 
         | Around the time of writing the code, comment-free code looks
         | clear to the author because they have the benefit of all of the
         | thinking that went into writing the code.
         | 
         | I'd argue that in production is when comments are often most
         | valuable. The middle of a crisis is a terrible time to wonder
         | what assumptions were made when writing code a specific way, or
         | if a certain line of code that seems to be doing something
         | weird really is weird or if it was based on something you're
         | not considering. It's also the time when you want to maximize
         | the number of people that can jump in and help.
         | 
         | Everybody has their own coding standards and there is certainly
         | some subjectivity to those standards. Here's mine for people
         | who work for me: if you don't document your code, you have no
         | business touching anything that goes anywhere near production,
         | you can't do anything that is critical path, and you should
         | make a sincere effort to change or start looking for another
         | job. :)
        
       | twiddling wrote:
       | Having done some "code archaeology" in my past, I loved coming
       | across a good comment block, with clear rationale as to why
       | something was done, which looked incorrect if you only had the
       | code.
        
       | davidw wrote:
       | I worked with some Rails folks a while back who were utterly
       | convinced that comments were to be avoided because it meant your
       | code was not clear.
       | 
       | I agree that comments explaining 'what' is happening are mostly
       | useless. Write clearer code. But 'why' comments are good. Most
       | things can be coded up different ways. Tell me why you chose this
       | way. Tell me about constraints that might not be immediately
       | obvious. Let me know if indeed, it could be cleaner, but you were
       | in a hurry (this is a thing that happens in the real world), or
       | if it's that way for a specific reason.
        
         | claytonjy wrote:
         | I worked at a late-stage Rails-based startup that had "dont
         | write comments" as an engineering principle!
         | 
         | The python folks before me used this to avoid writing
         | docstrings for modules/classes/methods, so code could only be
         | understood by reading the entirety of it. Throw in some deep
         | class hierarchies and it was very hard to onboard there.
        
         | adamwk wrote:
         | I went from a rails developer to iOS; Apple and iOS developers
         | in general are pretty good at comments, and I now value them
         | more. Comments at the API level mean I don't have to go diving
         | however deep to find out what a method does. If they're really
         | good, they can also be used to distinguish the specification
         | from what's actually happening when there are bugs.
         | 
         | In the simplest cases, sure you don't need to write "getName
         | returns a user's first name and last name separated by a space
         | character," but I'm guessing the method requestPurchase will
         | have a lot of nuance and I hope it's documented (yes, even the
         | "what happens")
        
         | rubyist5eva wrote:
         | As a "rails folk", we aren't all like that :)
        
         | ed-209 wrote:
         | Small, well named functions have served me well in this regard,
         | eg.
         | 
         | if (theWhy()){ theWhat() }
        
         | latchkey wrote:
         | Document the why, not the what.
        
           | collyw wrote:
           | A lot of code is WTF enough that a comment explaining what it
           | is attempting to do might be helpful. The real world is full
           | of absolutely shit code, but it still earns the company
           | money.
        
             | latchkey wrote:
             | Hmm... I think you might be missing the concept a bit. What
             | I mean is that there is a lot of documentation that is like
             | this:                 /*        The phone number       */
             | private static String phoneNumber;
             | 
             | That is considered 'the what', the documentation doesn't
             | explain 'why' the phone number is a field on the class.
             | This might be obvious because the class is called
             | 'Address'... so people will argue that it is self
             | documenting, and it is.
             | 
             | The WTF code is 'the why'...
        
         | corytheboyd wrote:
         | Having worked with Rails folk for many years, they do have some
         | weird strong opinions, this being one. The argument that
         | comments shouldn't be made because they'll "become stale" is
         | pretty lame IMO. It's either not a big deal or the end of the
         | fucking world for some reason lol. Maintaining code is just...
         | work. You just do it. That includes comments.
        
           | mgkimsal wrote:
           | > The argument that comments shouldn't be made because
           | they'll "become stale" is pretty lame IMO
           | 
           | Better not write tests either, because those will become
           | stale too.
           | 
           | And any sort of user documentation/support/etc. It'll all
           | just become stale.
           | 
           | It's almost as if code is just part of a larger 'thing' that
           | has to be maintained.
        
             | p1necone wrote:
             | (well written) tests tend to fail (or fail to compile) if
             | they're 'stale' though, so they force you to maintain them
             | just like other code.
             | 
             | (I'm not arguing against writing comments though - the
             | 'they'll get stale' thing is not enough to make them not
             | valuable)
        
             | jrumbut wrote:
             | The difference between tests and comments is that comments
             | become stale silently.
        
             | randomdata wrote:
             | _> Better not write tests either, because those will become
             | stale too._
             | 
             | They do go stale, but tests were invented exactly so that
             | your documentation is able to alert you when it has gone
             | stale. Their existence rests on being an attempt to solve
             | to this problem.
        
             | BurningFrog wrote:
             | When tests go stale the build goes red, and you know to fix
             | things.
             | 
             | Comments transition from truth to lie without any
             | indication.
        
               | vkou wrote:
               | > Comments transition from truth to lie without any
               | indication.
               | 
               | Only if you don't do code reviews. The reviewer should be
               | checking for this.
        
               | still_grokking wrote:
               | Only if you don't maintain your code.
               | 
               | Guess what: Comments are part of the code. Like all other
               | documentation!
        
             | tcgv wrote:
             | > Better not write tests either, because those will become
             | stale too
             | 
             | Unit tests are easier to maintain when incorporated to a
             | CI/CD pipeline. Then every pushed commit (or Merge Request)
             | will trigger the test suite to run and in case one of the
             | tests fails the team will know.
        
           | sky_rw wrote:
           | Rails developers (myself included) are lazy by design, and
           | thus eschew anything requiring redundant work. Most operate
           | under the principle that "it was hard to write, it should be
           | hard to read"
        
         | citrin_ru wrote:
         | Many people think their code is clear. The problem is it is
         | clear often only for the author and sometimes for a limited
         | time even for the author. If anyone else start to working with
         | the code questions usually arise. And you can prepare comments
         | for at least some of such questions.
         | 
         | In my practice I often see code where useful comments are
         | missing and hours of research required to learn something
         | author for sure knew. Code which has too much comments to me is
         | an imaginary problem - I've seen it at most a couple times in
         | my career and one of them was the code written by a junior
         | developer in a style one can expect in a tutorial or a book.
         | But usually people quickly learn to not add unnecessary
         | comments (and eventually start adding too little of them).
        
           | weatherlight wrote:
           | Many people think their subjective comments are clear! Code
           | doesn't lie, comments do.
        
             | MrGilbert wrote:
             | Yet, code might not tell the whole story. It's a pitty.
        
             | afandian wrote:
             | I wouldn't use the word 'lie' but plenty of Rails code I've
             | seen has mystery effects and hard to follow coupling due to
             | monkey patching and the like. Comments please.
        
             | lordgroff wrote:
             | So train people to write better comments, because although
             | code doesn't lie (questionable as that is since the intent
             | behind the code and what it does doesn't always align) it
             | can be literally the worst implantation of an algorithm
             | imaginable, and so we teach people how to code.
             | 
             | Teaching people how to comment is a skill that's just as
             | important and nothing turns me off a project faster than
             | the "code is its own documentation" mantra.
        
         | weatherlight wrote:
         | If this study is to be believed. Citation->
         | https://cacm.acm.org/magazines/2017/10/221326-a-large-scale-...
         | 
         | The 5 programming languages with the least amount of bugs are:
         | Haskell         Ada         Scala         Rust
         | 
         | *Drum roll please*                   Ruby
         | 
         | Ruby is nothing like the other languages above in design, but
         | that community has fantastic conventions around code clarity,
         | code quality, testing, continuous integration, etc.
         | 
         | Comments are for things like, `Todos`, Noting a specific
         | algorithm, maybe a link to a white paper, noting a violation of
         | a convention for speed, security, or some other performance
         | reason.
         | 
         | Comments are for things that are __impossible__ to tell from
         | the code.
        
           | tln wrote:
           | Interesting paper, thanks for posting. The paper goes on to
           | say:
           | 
           | > One should take care not to overestimate the impact of
           | language on defects. While the observed relationships are
           | statistically significant, the effects are quite small.
           | Analysis of deviance reveals that language accounts for less
           | than 1% of the total explained deviance
        
           | otikik wrote:
           | Agree with most of what you said, except on the
           | __impossible__ part.
           | 
           | You can tell _everything_ with code, _given enough time and
           | resources_. Nothing is  "impossible". But there's a point
           | where you hit diminishing returns. It's about efficiency.
           | 
           | Other devs, or your future self, will have to time trying to
           | build the same "castle in your head" as you did. Can a
           | comment shorten that time? If a one-line comment saves 15
           | minutes of investigation in aggregate, that's a no-brainer.
           | You should add it. Conversely, a line that says "add 5 to x"
           | is just wasting everyone's time.
           | 
           | As a general rule, once I have finally understood a
           | particularly hairy piece of code, I don't want to do it again
           | in 6 months. I have even done ASCII diagrams in the comments
           | explaining how a particularly hairy piece of code worked,
           | when I hated it enough.
        
             | lumb63 wrote:
             | In my experience, one man's "waste of time" is another
             | man's castle-in-the-head-building-time-saver. At my current
             | company, if I have reasonable, self explanatory code, such
             | as a function with the signature "read_page(page_num: u32)
             | -> PageData", they'll gather it reads a page with the given
             | page number and extracts the data. At my last company, if I
             | wrote the same code, I'd receive a comment on my PR
             | complaining I did not document it will enough. I would then
             | add a comment that somehow only I was able to detect was
             | snarkily written, something like "// reads the given page
             | number and returns its data" and they would be happy as
             | clams.
             | 
             | I always assumed that behavior was dogmatic until, over
             | many PRs, multiple members of the team commented that if I
             | commented my code, it would be much easier to read. And
             | comments of the above quality assuaged them.
        
             | jofer wrote:
             | ASCII diagram comments are surprisingly common in
             | scientific computing, FWIW. It's not so much that it's
             | always hairy code, more that it helps to add some
             | visualizations of what's going on. Math vs intuitive
             | understanding are often very different things.
             | 
             | It's something I wish was more common than it is. Sometimes
             | you really want that ASCII pseudo graph explaining how
             | minimizing this thing relates to that other thing that we
             | actually care about.
             | 
             | Taken a step further, I really wish we had better systems
             | for managing this type of information alongside a codebase.
             | E.g. the whitepaper, or presentation, or figures, or
             | whatever is often very necessary to understand the code,
             | and ideally it would be under version control and live
             | neatly alongside things. Nicely rendered docs definitely
             | help with this (e.g. latex in comments), but I'm always
             | surprised there aren't more people focusing on this aspect
             | of information management.
        
           | jaywalk wrote:
           | I wish I could get this point across to my team. They will
           | happily write:
           | 
           | db.insert(record); // save the record to the database
           | 
           | But when they write some crazy off-the-wall code (that's
           | usually because they didn't understand the proper way to do
           | something) I have to check the logs to see who wrote it and
           | ask them why.
           | 
           | Just the other day I was debugging an application that had a
           | 6 second sleep at the end of the main() function. I just
           | figured it was some dumb thing left in for debugging and
           | deleted it, because there's no good reason to do that. The
           | next day, the dev who put it in messaged me and said he put
           | it there because the application was exiting before it had
           | logged it's completion to our logging system. So I explained
           | that the proper way to do this is to flush the log, not just
           | hang the application for 6 seconds so that the last messages
           | just happen to go through.
           | 
           | If there was a comment explaining _why_ there was a 6 second
           | sleep, I could have just fixed it and educated the developer
           | without causing any grief.
        
             | weatherlight wrote:
             | thats a legit case of, "its impossible to gleam that fact
             | from the code and the code alone." (although I would have
             | left that as a comment for the reviewer in the PR) so if
             | theres a conversation around that decision, it would have
             | been captured there.)
        
           | j45 wrote:
           | Comments are critical at creating beginners to the code base,
           | something rarely the expert class think about accelerating.
           | 
           | For my code? I agree
           | 
           | Code for others to participate in? The simplest possible way
           | for the greatest number of developers to understand as
           | quickly as possible. Not about my best practice or preference
           | but for the greater good.
           | 
           | Coding standards for the elite devs are only so effective at
           | growing that growing quick enough.
        
         | paulddraper wrote:
         | What question will the next engineer have about your choice?
         | 
         | 1. Rewrite your code to make the answer obvious.
         | 
         | 2. If that's not possible use a comment.
        
         | randomdata wrote:
         | _> I worked with some Rails folks a while back who were utterly
         | convinced that comments were to be avoided because it meant
         | your code was not clear._
         | 
         | What this means is that if your Ruby code is clear it should
         | read like natural language. Injecting subtitles into the middle
         | of the expression
         | 
         | # I decided to phrase it this way because I was in a rush and
         | it was the first thing that came out. With more time I could no
         | doubt articulate this in a more communicative way, but for the
         | sake of a random post on the internet I'm not terribly worried.
         | 
         | interrupts the flow when one is reading the code, which makes
         | for a much less pleasant experience. Ruby may not be the only
         | language that is like this, but it is relatively unique in this
         | regard. Comments in other languages don't seem to cause the
         | same interruption.
         | 
         | # That's all I've got. Time to clean up.
         | 
         | I'm not sure this means don't provide additional information to
         | future readers that may be beneficial, but be discriminating in
         | where you put it.
        
           | davidw wrote:
           | > should read like natural language
           | 
           | The history of programming is full of that notion and it
           | never really works out. See: COBOL, SQL, and so on.
           | 
           | I think we can all agree that code that is easy to read is
           | better, but sometimes the 'why' needs spelling out.
        
             | randomdata wrote:
             | Totally agree. I even said so at the end. You would have
             | noticed if the comments didn't get in the way. :)
        
         | kawsper wrote:
         | Arkency, a very well-known Ruby consulting company (at least in
         | Europe), are the ones I've seen shout about this 'rule' the
         | loudest: https://twitter.com/arkency/status/1254784379190038534
        
           | latchkey wrote:
           | My time at Pivotal Labs was similar. "The tests are the
           | documentation!"
        
             | vkou wrote:
             | Oh? Their tests have 100% coverage of _every_ feature, and
             | _every_ meaningful interaction between features?
        
             | Yoric wrote:
             | I have worked with a few developers who shared this motto.
             | I didn't agree with them.
             | 
             | While it's anecdotal, my understanding is that we were
             | simply working on very, very different codebases. I was
             | refactoring multi-million lines C++ codebases, implementing
             | concurrent algorithms in which dependencies cannot be
             | expressed through language constructs and I had to make
             | non-trivial choices to prioritize performance, or safety,
             | or security at the expense of readability.
             | 
             | On the other hand, these (few) developers were working on
             | writing fresh code, with less footgunny languages, with
             | simpler data and control dependencies and didn't need to
             | make hard choices due to perf/safety/security.
        
       | zabzonk wrote:
       | i think comments can be very useful. for example, look at the c
       | function strlen:
       | 
       | int strlen( char * s );
       | 
       | the following comment pretty much describes what it does:
       | 
       | - if passed a null-terminated string, returns the number of
       | characters in the string, excluding the terminator
       | 
       | - if passed a null pointer, or an incorrectly terminated string,
       | behaviour is undefined
       | 
       | these are the kind of comments i like to see
        
       | catskul2 wrote:
       | I feel statements like:
       | 
       | "...team leads (and managers) allow comments to get out of sync
       | with the code..."
       | 
       | reveal a fundamental misunderstanding of how software
       | organizations generally work.
        
       | simonbarker87 wrote:
       | I've always pushed back against the "no comments, they go out of
       | date" sentiment.
       | 
       | Comments aren't milk, they don't just go off, developers let them
       | go out of date.
       | 
       | As others have said, comments should be used to add why, to give
       | context.
        
         | SpeedilyDamage wrote:
         | Why must that documentation go inline with the code? There are
         | so many better ways to document design and implementation
         | decisions that don't involve embedding English into source code
         | files.
         | 
         | We preach endlessly the idea of orthogonality and abstraction,
         | but then we smash together plain English and
         | Python/C++/Erlang/whatever?
        
           | simonbarker87 wrote:
           | If the information in the comment directly relates to the
           | code and is for developers then putting it next to the code
           | makes a lot of sense. Putting it somewhere else just
           | increases the likelihood it will go stale and decreases
           | discoverability of the information.
        
         | randomdata wrote:
         | 'Why' should be documented in your test suite. Leave a comment
         | too, but don't think you can skip out on the former because
         | you've done the latter.
        
           | citrin_ru wrote:
           | Tests can show what code is expected to do from the point of
           | view of the tests author. They usually have no information
           | why code works this way. Also I've seen more than a few times
           | tests which ossify wrong behavior. Tests need comments too.
        
             | randomdata wrote:
             | _> They usually have no information why code works this
             | way_
             | 
             | They need to if the the way it works is significant. If it
             | is not significant then the value of a comment becomes
             | somewhat dubious anyway as the code is expendable and
             | doesn't really matter. It is not necessary to understand
             | the program and if it is flawed you're going to rewrite it.
             | Comments can add a lot of value, but there is a line where
             | the value quickly diminishes.
        
       | doctor_eval wrote:
       | > Because the culture of many development organizations
       | undervalues comments, team leads (and managers) allow comments to
       | get out of sync with the code--thereby increasing technical debt
       | instead of reducing it.
       | 
       | Comment bit rot is inevitable, because comments don't compile and
       | can't be tested. The only way to keep them in sync is by hand,
       | which takes a lot of time and energy and is far from perfect. Of
       | course,
       | 
       | > The first problem is that most developers are under great time
       | pressure and don't have the time to make the code so utterly
       | clear that it requires no further comment.
       | 
       | So they don't have time to write the code clearly, but they
       | somehow magically have time to read and review all the comments
       | and to keep them in sync with the code? And the reviewers too?
       | 
       | "If only developers worked harder...". It's nonsense.
       | 
       | Comments are great, they have an important place in software
       | engineering, and I always regret when I forget to write some in a
       | file or class. But they are not a silver bullet, and must be
       | treated with suspicion, because there is no way to prove if they
       | actually describe what's going on. And that's the same reason
       | that they are hard to keep in sync.
        
         | SpeedilyDamage wrote:
         | If I've written a comment, and I have, it's because I have to
         | move on, _not_ because I think it 's adding an extra layer of
         | quality.
         | 
         | I don't _want_ to write a comment, I 'd _rather_ write clean
         | code that looks good, but when I run out of time to spend on a
         | problem, and I don 't think the code is clear enough, I think
         | _then_ it 's acceptable to add a comment.
         | 
         | I just think too many devs have their egos wrapped up into
         | their jobs, so hearing, "Commenting is failure!" evokes an
         | emotional response. What these devs don't realize is you can
         | make no mistakes and still "fail" to write clean code, and
         | that's totally okay.
         | 
         | Uncle Bob is just saying that pulling out a comment before
         | you've tried is premature. Try to avoid it first, if you have
         | time to.
        
         | jonfw wrote:
         | Great thing about Git, is you can look at the code at the time
         | when the comment was written, and still retain the original
         | value of the comment.
         | 
         | If there have been major structural changes that make the
         | comment useless- that'd be pretty easy to see, it's very easy
         | to delete comments
        
       | revskill wrote:
       | It's time to get comment generated via toolings.
        
       | ChrisMarshallNY wrote:
       | I have come to a "middle ground," when structuring and commenting
       | code.
       | 
       | First, the code needs to be fairly clear, but not "stupid" clear.
       | I have had people tell me not to use idiomatic Swift, because "a
       | JavaScript programmer can't understand it."
       | 
       | In some cases, this may be necessary, but not in mine.
       | 
       | The #1 consumer of my code, is Yours Truly. The wonkiness doesn't
       | bother me, but sometimes, I may not be aware of _why_ I did
       | something (that may not be  "idiomatic," at all).
       | 
       | That's why I may write a quick comment, like so:
       | showThrobber()             // The reason for this, is that we
       | need to give the throbber time to show up.
       | DispatchQueue.main.asyncAfter(deadline: DispatchTime.now() +
       | DispatchTimeInterval.milliseconds(20)) {
       | 
       | That explains the awkward use of an "asyncAfter()" method.
       | 
       | It was the result of me, wasting a good half hour, trying to
       | figure out why the screen didn't change. I saved future me, a
       | half hour (and also a signpost for "improvements needed").
       | 
       | I write about my approach to documentation, here:
       | https://littlegreenviper.com/miscellany/leaving-a-legacy/
        
       | MSFT_Edging wrote:
       | I always write comments, even on code I've written myself it
       | comes in handy.
       | 
       | 6 months later I wont remember why the "easy" solution wasn't the
       | path that was taken, or some complexity that needed special
       | handling in a single case that was discovered through a few hours
       | of debugging.
       | 
       | Sure you could write perfect code, but writing out your thought
       | process helps tremendously with understanding a thought process
       | and getting up to speed far faster.
        
         | alyandon wrote:
         | Same - if my code is complex enough to not be easily written in
         | a few lines I'll drop a comment about what it is doing and
         | maybe even why. It takes a minimal amount of effort while I'm
         | coding and saves a lot of time when I (or someone completely
         | unfamiliar with the code) have to revisit it months/years
         | later.
         | 
         | My guiding principle is that I don't want someone to read my
         | code years later, exclaim "Who the hell is this alyandon
         | guy?!?!" and be motivated enough to create a time machine so
         | they can go back in time and smash my keyboard to bits before I
         | wrote said code.
        
           | collyw wrote:
           | Likewise if I am using some advanced feature of the language
           | / framework, I think it's worth a comment.
        
       ___________________________________________________________________
       (page generated 2023-01-31 23:00 UTC)