[HN Gopher] I'm a productive programmer with a memory of a fruit... ___________________________________________________________________ I'm a productive programmer with a memory of a fruit fly Author : nalgeon Score : 308 points Date : 2022-09-19 16:04 UTC (6 hours ago) (HTM) web link (hynek.me) (TXT) w3m dump (hynek.me) | xor99 wrote: | You have volatile memory, very workable and useable imo lol | masukomi wrote: | Tell me you have ADHD without _telling_ me you have ADHD ;) | | Sometimes I'm not sure what's worse, the not remembering, or the | people claiming that you having forgotten means you didn't care | enough, or that you're not trying hard enough. grrrr | stronglikedan wrote: | Could just be ADD. ;) | unity1001 wrote: | Even if someone can remember every second in any given day with | picture-perfect detail, taking notes, documenting stuff will | allow him to do MUCH more than he normally could. | kazinator wrote: | > _On the other hand, the information for everything that we need | to write code today is usually no more than one click away._ | | Sure! If you just assemble a page with about 500 button or links, | and know which one to click on to get the needed information, | everything is a click away! | nyanpasu64 wrote: | I wish Zeal had per-doc-set custom CSS rules, and customizable | default zoom level. | mxuribe wrote: | Well, i suppose since the source code is simply a repo on | github, have you tried submitting these as feature requests | (via github)? Worth a shot, eh? (I do like the idea of the zoom | level adjuster.) | 01100011 wrote: | I started having this problem around 40. A lot of it came from a | heavy marijuana habit that seemed to reduce my working memory | with the tradeoff that I became more clever at small-scale | problems(I call it a tactical vs strategic tradeoff). | | Quit smoking pot and things got a lot better for a while, but | then things seemed to resume their downward slide. Sleep apnea | didn't help, and treating it made things better for a while, but | that slide continued. | | Now I just try to manage it with lots of notes, scripting | everything I can, and trying to simplify my workflow wherever | possible. Hopefully things stabilize in my 50s or I don't think | I'll be good for much engineering work beyond that. I have a | number of dopamine-related movement disorders though so there may | be some special issues in my case. | zwischenzug wrote: | This is an ad. | pessimizer wrote: | For the free thing that he's been giving away for 10 years, or | for his free newsletter? | hotdamnson wrote: | Time flies like an arrow, fruit flies like banana | [deleted] | nathias wrote: | it's mostly use it or lose it, I have to relearn a lot of the | unimportant things that get tested for jobs | hotz wrote: | It's a thing. Every couple of months I rehash everything. | impulse7 wrote: | I made something similar to have a key-shortcut quickly show a | 'cheatsheet' for whatever application window that is in focus in | i3(window manager). If no cheatsheet exists it opens an empty | document so I can fill it in and save it. | | https://github.com/tonybjorkman/i3-cheatsheet-hot-key | mileycyrusXOXO wrote: | I love this idea, I might have to implement this on my work mac | sitkack wrote: | Would be an apt use of http://www.hammerspoon.org/ | masukomi wrote: | I wrote Private Comments[1] specifically to address this problem | in code. My coworkers can maintain context about how a given | thing works months after the fact. I can't. So, I leave private | comments throughout the code. Things they'd never want committed, | but save me hours of re-leaning when next i encounter a given | piece of code. | | Currently has plugins for Vim (proof of concept) and Emacs | (actually good). It'd be lovely if one of you folks would make a | VSCode plugin for it. I've thoroughly documented the API and | diagrammed the code flow you'd need[2], so that this would be as | easy as possible to add to your favorite editor. | | [1]: https://github.com/masukomi/private_comments | | [2]: https://masukomi.github.io/private_comments/ | zwarag wrote: | Related Question: What have you done to improve your memory? | pessimizer wrote: | Never heard of Zeal before in my life; glad to have read this | blog. Also thankful to this guy for making it easier to get docs | into Zeal. People are the best. | mxuribe wrote: | Same here - neve knew Zeal existed 'til today! I also often | have numerous browser tabs open to a few different doc sites. I | know there are websites out there that provides something | similar (e.g. https://devdocs.io , etc.), but Zeal is *offline* | which makes it a wonderful thing! I just downloaded it on my | work machine, and love it! I'll be setting this up at home | machine too! Kudos to the crteators of Zeal, and for today's | promotors (TIL)! | pessimizer wrote: | I felt like an idiot thinking this thing must be obscure and | new, then finding out it was always an apt-get away. | mxuribe wrote: | Same here! :-) | sitkack wrote: | devdocs also work https://devdocs.io/offline | karmakaze wrote: | > Having all API docs one key press away is profoundly | empowering. | | > While Dash is a $30 Mac app, there's the free Windows and Linux | version called Zeal[1], and a $20 Windows app called Velocity[2]. | Of course there's also at least one Emacs package doing the same | thing: helm-dash[3]. | | [0] https://kapeli.com/dash | | [1] https://zealdocs.org/ [2] | https://velocity.silverlakesoftware.com/ [3] | https://github.com/dash-docs-el/helm-dash | BerislavLopac wrote: | Time flies like an arrow, fruit flies like bananas. | dekhn wrote: | it reads better as "time flies like an arrow, fruit flies like | a banana" | jbandela1 wrote: | "time flies like an arrow, fruit flies like an apple" | | Has even more similarity between the two halves. | marcosdumay wrote: | But they will always prefer a banana. | [deleted] | zomglings wrote: | - Terry Pratchett | dekhn wrote: | I don't think so. | timr wrote: | I have the same problem (i.e. terrible short-term memory, though | my long-term memory is fine), and I've picked up a number of | compensating behaviors over the years. By far, _documentation_ is | my #1 go-to strategy. I document code extensively, even if I 'm | the only person who is ever going to read it again. People have | mocked me for this, but I believe it's a superpower. | | Most programmers believe a number of blatant falsehoods about | documentation, with the most prevalent being "comments go out of | date quickly, so there's no point in investing in them". Maybe | I'm just hyper-aware of it because my short-term memory sucks, | but code comments have saved me on so many occasions that they're | simply not optional. | | You _can_ document your code. You _can_ keep it up to date. It | isn 't that hard. You just don't want to. | tayo42 wrote: | > You can document your code. You can keep it up to date. It | isn't that hard. You just don't want to. | | Yeah I can or an individual can, that misses the point of the | advice which is intended for groups on large projects with | deadlines. Like once a manager says get this done now and we'll | find time later for the rest... That never happens | zelphirkalt wrote: | Usually when writing some code, which deals with something new | for me, I get many "idiot questions" in my head. I try to write | comments in a way, which will answer my future self's "idiot | questions". Answering all those questions, I feel more like I | truly understand, what I am doing. | arithma wrote: | I often don't comment code, especially in personal stuff, but | when I occasionally do, which happens mostly when things get | overwhelming, I find bugs or fix things that I was stuck on. | Writing forces you to understand better, name better, and | almost feels like providing you with another perspective, all | without leaving your own self. | bityard wrote: | I think some people have run into a few cases where the | documentation is stale, and then reflexively generalize that to | "all documentation is stale." | | And that's patently absurd on the face of it. | closeparen wrote: | Depending on the nature of your memory and thought process, | the insights gained from potentially-false statements in the | documentation when they are true might be outweighed by the | blind alleys and misunderstandings generated when they are | false. You'd have to be very good at remembering where things | came from and tagging them with their level of certainty. An | important skill! But not a trivial one. | Jensson wrote: | > You'd have to be very good at remembering where things | came from and tagging them with their level of certainty. | | I wonder why not more people do this? Not just for code, | but for everything. I remember where I learned everything I | know, I don't trust anything unless I remember the source. | How do other people think, do they think that whatever pops | up in their head is the truth without any source? Then how | do they know it is a fact and not just a hunch or a guess? | hinkley wrote: | Docs don't go stale like bread. They atrophy from disuse. | | I always force the onboarding process to go through our docs, | and I spend a little time with each new person observing | their progress looking for regressions in the docs. You can't | get that with old-timers because of the echo chamber/curse of | knowledge effect. | | This breaks down when you have a place that never hires new | people. And rather than thinking that's a flaw in my process, | I'm starting to think that's a flaw in the business itself. | Without fresh ideas and feedback a project stagnates. | SkyMarshal wrote: | One way to cap the cognitive load of adding and maintaining | comments is to limit them to explain _why_ a piece of code does | what it does, rather than how. Rely on the fact that the how is | self-documenting to other programmers who may need to maintain | your code later (including you), but the why is not always so. | | Eg, were other options considered and this one chosen? Why? Is | this piece of code non-standard or particularly clever? Why? Is | this piece of code more complex than it seems like it needs to | be? Why? Does this piece of have non-local dependency that may | not be obvious at first glance? Are there security concerns | with this piece of code which are non-obvious to a novice or an | outsourced worker? Etc. | | There's the old saying, _" since debugging code is more | difficult than writing it, then if you write the most clever | code you are capable of, then you are by definition incapable | of debugging it"_. Pretend you're explaining your code to | future you who has forgotten why you did what you did and isn't | clever enough to debug it. | fishtoaster wrote: | I think "why" comments are the most useful, but "what" | comments are a bit undervalued. A few types of "what" | comments are, I find, very useful: | | 1. Comments that are effectively headers: # | If the user is foobar, do thing user = | User.find(current_user_id) | user.preload_bizbaz!(cache: false) is_foobar = | user.bizbaz.foobar.status == "yes" if (is_foobar) { | do_thing(user) } | | Yes, you can read the 4 lines of code to see the "what' - the | comment is duplicative. But when I'm skimming through a large | codebase trying to find or understand something, these | headers can be invaluable. | | 2. Comments on dense code # Matches any | email like foo@bar.com (only .com, .net, .org email | addresses) return | email.match(/^.*@.*\.(com|net|org)$/) | | Yes I can that regex, but I can read that comment a lot | faster. | coryrc wrote: | Those are perfect examples of what not to do. | vikingerik wrote: | And the latter is a perfect example of what goes wrong, | when someone adds "gov" to the regex but doesn't notice the | comment to update it. | Arrath wrote: | Next up: comments that dynamically generate from the code | itself, like tooltips in a game. /s | | "...only from %s domains..." | m000 wrote: | I love header comments, but many people fail to get their | usefulness, and I get the "good code does not need | comments" mantra recited to me pretty often. | | Here is the thing: Header comments are not really about | explaining their following code. They are about reducing | the lines you need to read to navigate through the code by | a factor of 5 to 10. Huge time-saver, and helps a ton | newcomers to become productive quickly. | ezkhimo wrote: | For your first example, use a method with a fitting name. | | Second one is not a good example, because I think it's a | very common pattern and email.match with com|net|org | provides enough context by itself. It's just bloat imo. | stavros wrote: | I feel like many people take the "comments will go out of date" | adage the wrong way. To me, it doesn't say "don't write | comments", it says "give your comments some love while you | code". | | It's meant to warn against letting comments become false, not | against writing them. To me, at least. | r24y wrote: | One thing that I believe is under-documented in code is | _business decisions_. The team arrives at a decision in a | meeting or informal discussion, and it leads to some code that | might be tough to understand without context. I'll usually add | a comment briefly describing the decision, and initial and date | it. | | Initially I would just link to a wiki page in a comment, but | occasionally these links break, so in my experience it's better | to include the notes directly. | Archelaos wrote: | It is often also useful not only to document the decision the | team arrives at, but also briefly write down what was decided | not to implement and why. This is very helpful when people | come in a few weeks later with a "new" idea that has already | been discussed, or in onboarding new people to the project. | redkoala wrote: | Is there a solution for this problem in real-life? | layer8 wrote: | Write things down. Use reminders. Place things where you will | notice them when you need to be reminded of them, like the | proverbial string tied around your finger. | lhuser123 wrote: | There are some "tricks". For example blending what you want | to remember with something memorable, creating a mental | picture & recall it a few times. That's what I got from the | book Moon Walking with Einstein. | BerislavLopac wrote: | Of course comments stay in sync with the code... if you're the | only one working on that code. As soon as you have multiple | developers, you can forget about it. | jjav wrote: | > As soon as you have multiple developers, you can forget | about it. | | That's only true if everyone can check in code willy-nilly | without any approval. | | If you require code reviews then that's just part of the code | review. No documentation update = no approval, just like | missing tests or bad code. | hutzlibu wrote: | "Of course comments stay in sync with the code... if you're | the only one working on that code." | | If I am in a rush to implement something and then am | sidetracked because of a stupid small bug, then I just fix | that small bug in the code. And then another one. In these | states I only pay attention to code, and not text. If I would | also have to read the text, then I would forget the original | task. | | So sadly no, comments do not automatically stay in sync with | code for me, unless I put in the extra effort of cleaning up | afterwards. | nso95 wrote: | Treat comments the same as code when you review PRs | babyshake wrote: | > Most programmers believe a number of blatant falsehoods about | documentation, with the most prevalent being "comments go out | of date quickly, so there's no point in investing in them". | | More broadly, a problem with our cognition is that when we | remember something right now, we often think it is unlikely or | even not possible that we wouldn't remember it a day, a week, a | month from now. | hutzlibu wrote: | Oh yes, that is a lesson I also learned the hard way. | Solution: documenting, taking notes and organising it all. | abstractbill wrote: | This is funny to me because we seem to be complete opposites! I | have a great short-term memory, but my long-term memory is | sadly completely trashed. I don't care if someone wants to | document their code, but I never actually _trust_ that | documentation to be accurate or up-to-date. I expect it to be | misleading and time-wasting, and so I only trust the code | itself. I personally only write comments for bits of code that | I find confusing, and I think it 's a bit of a failing when I | have to do that -- I'd much prefer to put in the extra time and | effort to rewrite the code to not be confusing. | | (I don't write code for a living these days btw, only for | myself. It's much more fun, and I get to not care anymore | whether other people think I'm wrong about things like these). | tharkun__ wrote: | This so much. I really don't trust most comments at all. I | think we also need to be explicit about the kind of comment. | | There are comments that are categorically always bad. These | are the "this code does X" kind of comments. Those go out of | date _really_ quickly in a shared code base. They don 't even | make sense for myself on a project I'm doing myself. The code | should read like the comment would. Almost like prose. If it | doesn't, I haven't made the code good enough yet. We no | longer live in a world where the code needs to only be | machine readable and unreadable to most mortals. We have the | luxury of being able to use good abstractions and extract | functions without worrying about code running slow because of | too many indirections, stacks that are too big etc. We _can_ | optimize for direct code readability! | | Then there are the "why" comments. Those can be invaluable. | If I assume I have the kind of good code I can just read as | to the "what is this doing", I can sparingly add information | to things that might seem unusual or weird or inexplainable. | | Same with tests mentioned in some sibling posts. Tests should | be written in a self documenting way. I like to name my tests | after what they're testing. Like "should behave in X manner | when doing Y to Z" from a user's point of view, not on a | technical level. User not necessarily meaning end user, say | if you're testing an API or library function. Different | language make this easier or harder but I do it in all of | them. Armed with that documentation of what my tests pre- | requisites are and what the expected outcome is, I can write | the actual test. I should be able to deduce the expectations | of the test from the test's "name", thus double checking that | I am testing the correct thing. Many tests I find in shared | code bases are utterly unreadable, have way too many | expectations and side effects and test too many things at | once. With the above technique there's usually only one or | very few expectations. If I parsed out the test names from | all my tests and just gave them to you as a document, it | should almost read like a documentation of all of the | expected behaviors of my piece of software. | JohnBooty wrote: | but I never actually trust that documentation to be accurate | or up-to-date | | This is like saying food is bad, because it can spoil. Sure, | but we have ways of preventing that and figuring out when it | happens. | | A simple git blame or history (or the equivalent) should | quickly answer a number of questions. Is the code | significantly newer than the comment? Who can I ask for | verification? etc. | | It's not perfect, but significantly better than the | alternative. | | Similarly, _presumably_ code changes are approved by | reviewers, who should be preventing the merging of code that | invalidates its own inline documentation without an update to | the comments. | ithrow wrote: | In what programming language? I find that with dynamic | languages comments help but they require to have more | discipline about documentation. | lootsauce wrote: | Yes, I am also in this camp. I document very rarely, only | when sure something is inherently complicated and needs to be | written down. A great example of this is often times odd bug | fixes related to the evolution of features, underlying | services and data structures deserve callouts often linking | to the bug in question. I do take quite a lot of care in | naming things, clarity in how things operate and what the key | data structures are. | timr wrote: | You may not remember, but you and I have had this discussion | while working together. You were probably one of the people | mocking me. ;-) | | > I never actually trust that documentation to be accurate or | up-to-date. I expect it to be misleading and time-wasting, | and so I only trust the code itself. | | Two things here: | | 1) I don't implicitly _trust_ comments. Obviously, the code | is the definitive source of reference, and where the comment | differs from the code, it only means that something | _interesting_ happened. But... | | 2) I believe in commenting "why" or "who", and less often, | "what" (and rarely "how"). My experience is that "why" | comments age well -- even if the code drifts, the intent of a | method or class changes infrequently. | | For example: # I (timr) wrote this method | because I needed a way to # invert the index for | {situation}, and {method a} and # {method b} didn't | work because {reason}. | | is a better, more evergreen comment than: # | this method inverts the index for {situation}. | | which is _far_ better than: ## # | inverts index. # @args foo, bar, baz # | | Unfortunately, nearly all doc generation software encourages | the latter, and so many comments are pretty darned useless. | The first example is great because even if {method a} and | {method b} and {reason} fail to be true in the future, some | other programmer can come along and read it and say _" ok, I | understand why this was written this way, and the | preconditions motivating it are no longer valid. maybe I can | refactor."_ | | This is hugely valuable. | abstractbill wrote: | Oh wow! No, sadly I don't remember that, nor much else from | that long ago. That's funny (assuming I wasn't a dick about | mocking you!) | | I actually completely agree with your ordering of least- | useful to most-useful comments. I still tend to view these | most-useful comments as just kind of interesting historical | tidbits, rather than something that really helps me do my | job, but at least we agree on the order :) | hinkley wrote: | We have some blatant falsehoods about how documentation should | be organized as well. Virtually everyone seems to think that | people know which file to open, and so we organize files as if | the person is always in the right place. | | This doesn't scale, because as the size of the project and the | number of docs increases, we start refining generic knowledge | into more refined slices of the problem domain. At first the | docs are so far apart that you rarely miss, but as time goes | you miss more and more. So while your outline might suggest | that finding docs grows logarithmicly, it's linear at best. | | The first line of any doc should answer "where am I?" and "why | do I care" because the odds that they _don 't_ care go up over | time, and people put a time limit on self-service. After 2-3 | wrong pages in a row they start getting impatient, unless they | got through those wrong pages in 5 seconds apiece. | seti0Cha wrote: | I'm in exactly the same position. My memory is awful so I write | notes to my future self. It's not hard to keep comments up to | date if you keep them near the code and don't use a lot of | boilerplate. | timr wrote: | > It's not hard to keep comments up to date if you keep them | near the code and don't use a lot of boilerplate. | | Yep, exactly. It only gets "complicated" when you start | having these heavy-handed doc generators that are parsing | your code and breaking the build. | | I feel pretty strongly that sphinx, rubydoc, python | docstrings et al. are fine tools, but you have to have a | light touch with how they're applied. Autogenerated external | docs are a separate problem, and shouldn't discourage | developers from commenting their code. | amalcon wrote: | "Comments go out of date quickly" is true -- it's the "there's | no point in investing in them" that's incorrect. In addition to | being valuable in the short term (to both you and anyone else | who ends up looking at the code), "comment just became | outdated" is a highly valuable signal that a prior assumption | made by other code could now be false, and you should look into | that. | branko_d wrote: | I practice something I could only describe as "comment-driven | development". Whenever I need to implement something non- | trivial, something that might have subtle edge cases or has to | be done in a certain way because of the external dependencies, | I _first_ write the comment before writing the code. I might | iterate on the comment, not unlike one might iterate on a | design document, and basically use it as a mental tool to fully | understand the details of what needs to be done. After I do | that, I use the comment to remind me about all these details as | I go through the implementation. | | All this is doubly important when designing an API, where the | comment (also) serves as the externally visible documentation | for that API. It helps me put myself into the shoes of the | caller reading that documentation without knowing the | implementation details, which I believe helps me design a | better API. | | I hear that "comments go out of date" a lot, but in my case, if | a comment doesn't match the code, it's usually the code that | needs fixing. | swayvil wrote: | I do the exact same thing. Psuedo code it up and that's my | comments basically. | mjrpes wrote: | That sounds a bit like Donald Knuth's method of literate | programming: | https://en.wikipedia.org/wiki/Literate_programming | | "The literate programming paradigm, as conceived by Donald | Knuth, represents a move away from writing computer programs | in the manner and order imposed by the computer, and instead | gives programmers macros to develop programs in the order | demanded by the logic and flow of their thoughts.[4] Literate | programs are written as an exposition of logic in more | natural language in which macros are used to hide | abstractions and traditional source code, more like the text | of an essay." | ouid wrote: | it is natural that the first language you would choose to | write your program in is something that you can natively | compile. | dotancohen wrote: | I do the same thing. I then replace the comment with a method | name that describes exactly what the comment described, e.g. | _getLowestFooIdFromBarCollection(). I then implement the code | inside this private method. | marcosdumay wrote: | Usually, when I do this, I immediately end up with a comment | that doesn't reflect the code, and is cut and moved around so | many times that it's not legible anymore. So I try to replace | the comment with code, at once or piecewise (on what case, | the comment doubles as a TODO list) during the process. | dboreham wrote: | I've been doing this for decades. Possibly influenced by | beginning my career coding in assembly, os possibly by Knuth. | suprjami wrote: | This reminds me of an anecdote about code which was always | beautifully commented. | | The author would code while wasted and couldn't remember | anything if it wasn't on the page in front of them, hence the | comments. | vincnetas wrote: | If i could i would upvote this 10x times. Always write | documentation (especially for your own code). Future you will | say thank you to todays you. At least i have done so multiple | times. And i always feel cheating my self when i feel lazy to | write documentation. | yshrestha wrote: | I have the same problem. Rather than fight it, use it as your | superpower. I find it helps me write easier to understand | abstractions because I can't physically hold enough in my head | to understand anything more complex. Same is true for | documentation! | gleenn wrote: | _If_ you are diligent about documenting AND updating, sure, | seems very reasonable. But most people aren 't. You know what | the best documentation is? Working tests, much harder to have | wrong tests than wrong documentation. Even some of the largest | projects like Ruby on Rails have had incorrect internal code | docs. | twobitshifter wrote: | Show me a set of tests that I can use to build something more | easily than using the documentation? It sounds like just | kicking the can down the road to the next person. | timr wrote: | No. Tests are not documentation. Tests are tests, written in | code, which must be explained. You should document your | tests, too, because I _guarantee_ the next programmer won 't | understand your tests as well as you (think you) do. Also: | the "next programmer" will be you in a year. | | This is maybe a close #2 on the list of documentation | falsehoods that programmers believe. | wizofaus wrote: | I wouldn't describe it as a "falsehood that programmers | believe", just one of those perhaps unfortunate realities | that exist for some codebases that have a decent set of | unit tests but little else in the way of up-to-date | documentation that explains all edge case behaviour etc. | The only documentation you can really trust is that which | 100s of others rely on regularly, but a significant | percentage of the code most of us work with isn't going to | fulfill that criteria. | seti0Cha wrote: | Explaining edge case behavior is one use-case for | comments, and not the most valuable one in my estimation. | Aside from that, often incorrect edge case handling is in | both the code and the unit test because the problem is | that the developer didn't understand the requirements. In | my experience, in an undocumented and difficult codebase | the tests will be as mysterious or unreliable as the code | itself, which makes sense since they are usually written | by the same people. | wizofaus wrote: | You'd be surprised. There are generations of programmers | now who think nothing of writing 20+ unit tests with | quite clear names demonstrating what the behaviour should | be under a variety of conditions, but with virtually no | other documentation. Especially true in dev shops that | have high coverage requirements for a successful ci | build. | sodapopcan wrote: | Yes. Test _can_ very much be documentation if you write | them as such, although they aren't complete documentation. | Tests are the specification, ie the the how---documentation | provides the why. | | Test can be written to tell a story but most people aren't | taught this way (or simply don't buy it or don't write | tests). | marcosdumay wrote: | No, tests are not specification, they are examples, | specifically on the form "do this, and this happens". | | Imagining a specification out of this is like solving | those problems of "what is the next number on this | sequence: 1 18 31". It's simply can not be done, you can | guess something, but you will never know if it's the real | answer. | appletrotter wrote: | > You should document your tests, too, because I guarantee | the next programmer won't understand your tests as well as | you (think you) do. Also: the "next programmer" will be you | in a year. | | I hear this a lot, but I haven't found the same with | myself. I can read and understand old code I wrote. | | I attribute it to my IQ being mostly held up by reading and | writing comprehension skills. The way I process information | makes it easier for me to remember and understand old code | (I believe), compared to a lot of programmers whose inherit | skills align more closely to things like math and logic. | | Documentation can be a rabbit hole for me, and I often | don't feel I benefit from it within the code. | | I appreciate this is as good tactic for many people, but | implying it's for everyone is too dogmatic. | hodgesrm wrote: | You are right about commenting tests, but it seems wrong to | categorically reject their value as documentation for | users. I use tests all the time to get code examples and | understand what's actually supported. One of the great | things about open source projects is that you can _see_ the | tests. | layer8 wrote: | Tests may describe the what, but they don't explain the why | and the how, which are the important parts. | jjav wrote: | > You know what the best documentation is? Working tests | | Tests do have a slight overlap with documentation, but it's | that, only slight. | | If a piece of code has some weird non-obvious behavior, the | presence of a test for that particular behavior is a signal | that it's actually intentional, not a random bug. | | But, it doesn't tell me anything why that design choice | happened. That's what the documentation is for. So facing | such code, I sure hope it's well documented. | JohnBooty wrote: | Tests verify _what_ the code is doing. And I agree: they are | a great source of insight when understanding an unfamiliar | codebase. | | However, comments are typically better at answering the | _why._ If you are diligent about | documenting AND updating | | I don't understand why this is viewed as challenging. Writing | a sentence or two here and there is orders of magnitude | easier than writing the code itself. And any code review | process should help to prevent situations where the code and | comments are out of sync. | | Lastly, I feel like there's a larger human issue. I write | comments to explain certain _why 's_ in the code because I | care about my teammates and I care about the project. | | If others don't do the same, I think it speaks to a lack of | care for their fellow engineers and the work itself. I think, | "I just spent five hours figuring out something that you | could have explained with a single 30-second comment?" | | I'm baffled that some engineers think that this is okay. | mgaunard wrote: | Code is already a formal specification of what the machine is | set to do. | | All your documentation can do is make it more ambiguous. | Usually the documentation is wrong as well, but that might be | because the programmer didn't know how to specify clearly what | he wanted. | timr wrote: | > Code is already a formal specification of what the machine | is set to do. | | I take back my other comment where I said that "tests are | documentation" is the #2 falsehood about documentation that | programmers believe. _This_ is the #2 falsehood. | | Yes, "formally" the code is the spec. That doesn't help _you_ | very much though, squishy human, because you 're not a | computer. | mgaunard wrote: | Competent programmers should know all the fine details of | the programming language they work in, in effect being | human compilers. | jodrellblank wrote: | if this is a useless comment: // set i | to 1 int i=1; | | and this is a useful comment: // there | is a method overload which accepts an array, // | but it's buggy and crashes. workaround: cast to tuple | first. ... | | then you seem to be assuming people only want to write | and read the first kind. Because no matter how well you | 'know all the fine details of the programming language', | comments can tell you things the code can't. | | Even aside from the pointless gatekeeping of "competent | programmers" - ok what about people who aren't employed | as programmers but still need to read and write code? | What about the people who just have to deal with it being | an unfamiliar language because nobody who knows the | language is available? | 8note wrote: | Is that a useful comment? Seems more like a check style | entry. | | That comment will apply to every time the overload is | available, not for this instance of the call | 8note wrote: | If English is your fourth language and Java is your second, | the English comments aren't necessarily better for the | human. | daotoad wrote: | We need to write code that is optimized for communication and | clarity. We have a number of tools we can use to craft | communicative code. | | 1. Variable and function names. These should be descriptive and | never deceptive. For example, I've seen metric tons of code | like this `const json = makeSomeApiCall(params)` where the | contents of `json` is a the decoded response data and _not_ a | JSON string. This code is deceptive and obfuscatory. But if you | write `const decodedFooResponse = makeSomeApiCall(params);` | then you are accurately describing what the value is. This is | particularly import in untyped /loosely typed languages where | the value of the variable could be _anything_. | | 2. Code structure and layout. When writing prose, we achieve | clarity through structure. Code is no different. Keep related | things together. Avoid run-ons. In other words, write code that | has smallish functions, with smallish interfaces, it's easier | to reason about how the code will behave. Avoid unnecessary | mutation of values--repeated mutation of the same value is | particularly pernicious. Use white space to create visual | separations of distinct ideas. Use abstraction and | encapsulation to keep code focused. Avoid deeply nested | conditionals, flattening the tree whenever possible. And a | million other strategies that can all help. | | 3. Tests. Tests can be documentation, but they certainly aren't | always. They also aren't convenient documentation--what they | offer isn't going to show up in your editor when you inspect a | method. Unit tests are a nice way of recording verifiable | expectations for behavior. But if the test code is complicated | or poorly organized, all it does is compound the misery of | working on a messy codebase. | | 4. Comments are distinct from documentation here. Comments are | little side notes like "this implementation is a bit of a hack. | It is brittle because .... but we decided to keep it because X. | See someURL for contemporaneous discussion." They tell us why a | thing is the way it is or about some sort of risk or unexpected | detail. | | 4. Documentation is absolutely a part of making code | understandable. These docs are primarily going to be used in an | IDE/editor when viewing function signature data. Ideally you | can write JavaDoc/TSDoc/POD or similar inline docs. Examples | are worth their weight in gold. | | We should be using all our tools to write communicative code. | We don't need every technique for every line or block, but over | the scope of a package or project, we should judiciously employ | them all. Every line added comes with a concomitant maintenance | cost--we must ensure that every line we add is worth that cost. | jarjoura wrote: | This should be the top reply! | | Just want to add my extra take on comments: | | Comments are absolutely necessary when explaining complex | logic that is hard to read for the casual reader (or yourself | 6 months later). | | Comments are not necessary when the code itself explains what | it does by being clearly named, isolated and organized. | | Comments are not documentation and shouldn't be used as such. | They are tools to improve code clarity for the person who is | changing the code. They are not tools for someone who is | using the code. If the intent is to teach someone what the | code does so they can use it somewhere else, write | documentation in a wiki with examples and link the wiki URL | to that point in the code. | psygn89 wrote: | I agree it's a lame excuse not to document code, however there | are just some parts that just changes way too often by multiple | people where outdated comments can actually lead you astray. | The stuff I touch doesn't change often so I'll comment to | explain the weird and ambiguous looking parts. | timr wrote: | I'm not saying you have to document each line of code with | equal rigor. In fact, there's an art to knowing what to | document, and like most arts, you get better at it over time. | Sometimes I feel silly about what I've documented and what | I've neglected, but that's OK. I learn. | | The "code changes way too often" excuse is basically a | restatement of the myth that I wrote above. Yes, code changes | over time. It's pretty easy to change the comment with the | code, when necessary. The team members who _don 't_ do this | aren't doing their jobs. | | But at the end of the day, even if code deviates from | comments that's still fine. Having an outdated, well-written | comment is a historical record of what the code was | _supposed_ to be doing. That 's useful. | treeman79 wrote: | I used to have an amazing working memory. Could keep a dozen | things in mind at once. Or context switch fast enough to be the | same effect. | | Had a series of strokes. Mostly recovered but now short term | memory is one thing at time. | | I have leaned to document like crazy as I'm working. | | Todo lists are my life now. | 0xbadcafebee wrote: | A comparison of documentation generators: (https://en.wikipedia.o | rg/wiki/Comparison_of_documentation_ge...). Sphinx and Doxygen | seem to be the ones still maintained with the most features. | | _Old man mode_ | | Remember back when Linux systems just came with huge packages of | documentation? You could do anything offline by reading man pages | or looking through /usr/doc/, /usr/share/, etc. | sitkack wrote: | And on FreeBSD you have an entire monorepo that is the full | source to the system, you could REBUILD THE WORLD, not just the | kernel. | carvking wrote: | I've found https://beta.openai.com/playground to be quite good | for simple things, | | Takes a couple of times to get the questions right - but worth | it. Only complaint is that it is not instant. | tpmx wrote: | May be a variant of http://www.paulgraham.com/submarine.html | (regarding "Dash") | | But perhaps I'm exaggerating? I'm basing these concerns on what | we learned about the creator of Dash here, in 2016: | | https://news.ycombinator.com/item?id=12684265 | | (To be clear, the creator of Dash has a different name than the | author of this post.) | | There was IMO highly manipulative behavior that fooled a large | part of HN back then - to the degree that I remembered it just | now, six years later. | throwaway576652 wrote: | I don't remember anything. But my work notes have thousands of | lines. So if need to recall something, I just use Ctrl+F. | swah wrote: | That's why I'm paying for Copilot now... but with the fear that | using this just makes my memory even worse. | idlehand wrote: | Copilot has got me writing some side projects in Java again. I | love the fast compilation speed, good enough type system, | strong and seamless IDE support, and the abundance of | libraries. | | The new language versions with things like records take a lot | of the tedium away, and Copilot gets rid of most that is left. | ajudson wrote: | Memory is important, it doesn't matter how nice your | documentation search is http://augmentingcognition.com/ltm.html | lanstin wrote: | Arguably programmers who have great memories are much more | likely to write unmaintainable code, 'just edit these fifteen | files to add a new financial type' | | Once and only once is a requirement for people that can't | remember as much but also for good code. Consider it a | requirement for code organization and tools:if it takes longer | to look up than remember then the tooling needs a bump. | Obviously during heads down green fields coding, the cache will | get filled efficiently of wjatever is needrd, but by the time | v1.1 rolls around a good reread and rethink might be a good | idea | | Also, the key skill isn't memory but rapidly and well learning | new things. My C, perl, and jquery knowledge is well forgotten | and replaced with python, go and terraform and i am considered | trying out Rust. | bamboozled wrote: | Man this is crazy true, I work with people who are | ridiculously "intelligent", seemingly have amazing memories. | They seem to right the worst code. | yodsanklai wrote: | > Arguably programmers who have great memories are much more | likely to write unmaintainable code, 'just edit these fifteen | files to add a new financial type' | | Very true. Some programmers have higher tolerance for complex | code. Which is often why there are disagreements over | refactoring. | croisillon wrote: | The post has been written tomorrow? | LouisSayers wrote: | It's called time zones, the world isn't your country. Welcome | to the future. | pessimizer wrote: | It's not the 20th in Germany yet. | Computeiful wrote: | Wouldn't it be better to save the publication datetime as a | Unix timestamp, then convert it based on the reader's | timezone? | f311a wrote: | Yeah, but since the author leaves in EU I think it's just a | typo | no-dr-onboard wrote: | The author might be in Aus/NZ. | tpmx wrote: | The author writes that he's in Berlin/DE. | denysvitali wrote: | Then it's simply wrong. In Berlin, at the time of writing | this comment (which is anyways after he published the | article) is September 19, 2022 :) | [deleted] | outworlder wrote: | It's probably not correcting for timezones. | | Either that or the programmer forgot what day is today. | wonderwonder wrote: | They forgot what day it is | xavdid wrote: | I've noticed as I've gotten older that I lean more on remembering | pointers to information rather than the specific information. I | know something exists and can find it quickly, but may not know | it off the top of my head. | | For example, how to get the length of an iterable in a given | language. I may not remember the function name (or if it's a top- | level function vs a method) but I know I can search "string | length in $LANGUAGE" and find it. This scales better than | memorizing every language feature I'll ever use. | | --- | | PS: Dash is a great mac app, highly recommend. Your job will | likely cover it if it's something you think you'll use. | phist_mcgee wrote: | I think one of my greatest improvements as a developer over | time is my ability to sift and sort information very quickly. I | don't need to remember a lot of details, but like you said: | remembering pointers to information. | | Combine these pointers with google and an intuition for finding | relevant information, I will nearly always arrive at the | correct information/solution. | | It's like a muscle, you have to keep training it. | idlehand wrote: | Definitely agree with this. | | I've stopped worrying about remembering details, and just | assume that my neural network brain will figure out what is | worth retaining. Sometimes it does, sometimes it doesn't, but | life goes on. Not having anxiety about forgetting things feels | wonderful. | | Very often it's a lot easier to remember the journey to a piece | of information than the information itself. I remember reading | about some Greek scholar who'd imagine his long speeches as | walks, which helped him memorize them. I think we are more | suited to learning journeys than destinations. Maybe there's | simply more concepts to connect neurons to. | | Tangentially, I've gotten better at remembering walks and | drives as well, not through any conscious effort, but simply | cultivating a sense of curiosity about the world around me. The | more I learn about how the world fits together, the more | interesting tidbits I notice in a location, and when I see the | same place again it reminds me of the previous time I was | there. | soulofmischief wrote: | This is the basis of transactive memory. You maintain a | transactive memory with a collection of tools some call the | "external brain" like text pads, calendars, search engines and | more. | | https://en.wikipedia.org/wiki/Transactive_memory | simonw wrote: | > For example, how to get the length of an iterable in a given | language. I may not remember the function name (or if it's a | top-level function vs a method) but I know I can search "string | length in $LANGUAGE" and find it. | | This is actually a really good example of something I've | started using GPT-3 or GitHub Copilot for. | | If I'm in a Rust program and I don't know Rust, I can type | | # set a to the length of the items array | | And Copilot or the GPT-3 Playground (if I don't have Copilot | handy) will write the next line of code for me, without me | having to go and look up how to do length-of-array. | Someone wrote: | Before reading the article, I googled whether "the memory of a | fruit fly" is a compliment. It's not. | | https://kids.frontiersin.org/articles/10.3389/frym.2017.0006...: | | _"Normally, flies will remember very well and will get an A if | they are tested a few minutes after learning. But if there is | long time between learning and testing, which for a fruit fly is | 1 day, they will forget and get an F"_ | | A fruit fly lives for 40 to 50 days, so 1 day isn't a long time | to remember things for them. | | https://phys.org/news/2017-03-fruit-flies-memory.html: | | _"Flies form a memory of locations they are heading for. This | memory is retained for approximately four seconds. This means | that if a fly, for instance, deviates from its route for about a | second, it can still return to its original direction of | travel."_ | | I couldn't find how many things they can remember simultaneously. | poo_tan wrote: | 40 to 50 days... that's quite a bit of time! | Melatonic wrote: | Simple solution: You need to download more RAM! | f311a wrote: | Too bad we don't have a modern replacement for the man command in | terminal that could provide the same features. | swah wrote: | Warp terminal (MacOS only, got some backslash here for | requiring a log-in) has a feature for helping with this: | https://docs.warp.dev/features/workflows | inetknght wrote: | Even if we did have a "modern" replacement it would probably | say something like "there are a lot of features and you should | explore the interface to discover them!" | mgaunard wrote: | Using third-party libraries may be more costly than developing | your own. | | It's much easier to modify and maintain your own software which | is purpose-built to your needs than it is to maintain somebody | else's code that was built to their needs, and was probably | overcomplicated to make it as a generic library. | | For a compiled language, you have the extra complexity of | integrating its build system into yours. | | So I'd say you should still weigh carefully whether you want to | pull an extra dependency or not. | idlehand wrote: | Your own code is as foreign as a third party library to a | developer who hasn't been part of the writing process. | | Third party libraries which have a handful or more users are | generally speaking relatively bug-free for standard use cases. | | Third party libraries are generally a productivity win for | languages which have decent build systems, which is most of | them notably excluding C and C++. | dkjaudyeqooe wrote: | I don't try to remember anything and really don't see the point. | There's no way you can remember everything you need, so why even | try? | orangepurple wrote: | Creativity | | The rate at which you assimilate and synthesize new information | on a particular subject is proportional to how much other stuff | you already know about that subject. | | Its also only really worth learning things that matter or might | matter to you in the future, so there is a degree of | speculation and risk involved. | ianbutler wrote: | And here are the docset feeds, which link to the actual docsets | on Kapeli for Dash. | | You of course can't use them without permission, but I've found | them interesting before. | | https://github.com/Kapeli/feeds | jbandela1 wrote: | > Your mind is for having ideas, not holding them. | | I will have to disagree. New ideas are rarely totally new, and | often build on old ideas. Keeping old ideas in your brain will | help you come up with new ideas. | | One of the big advantages of having stuff in memory is that you | can do background processing. | | I can't tell you the number of problems I have figured out while | going for a long walk, or driving in my car, or even sleeping | (all of a sudden I wake up with the solution). | JohnBooty wrote: | Keeping old ideas in your brain will help you come up with new | ideas. | | Agree! Though, "Your mind is for having ideas, not holding | them" doesn't mean that you should literally never remember | anything. It's just not necessarily clear from context-less | quote. I can't tell you the number of | problems I have figured out while going for a long | walk | | Happily, you are in agreement with the author of the quote - | https://en.wikipedia.org/wiki/David_Allen_(author) | | The point is not to forcibly resist remembering things. The | point is to free yourself from the burden of remembering things | that can simply be filed away (ie, reference documentation) so | that you can be more present, focus on what's important, and | free your mind up for more creative/productive thinking - | including those walks where many of us get our best thinking | done. :) | falcolas wrote: | When I first read this line, I misread it as: | | > Your mind is having ideas, it's just not holding them. | | which is still quite accurate, especially given the theme of | the article. Augmenting your memory is important, especially | since age can make memorization harder, and even impossible. | i_am_toaster wrote: | I was really excited because I have the memory of a goldfish but | am the most hyper-productive person I know. I was curious about | the techniques and a write up on various techniques that this | person uses to compare them with my own. | | Then 2 paragraphs in I run face first into a 5 meter high | stainless steel marketing pitch. Wtf. | orangepurple wrote: | Improving your own brain with memories and knowledge is like | greatly increasing the size of a CPU L1 cache and the improvement | in execution performance is similar | poo_tan wrote: | Love the analogy. | zibby8 wrote: | CPUs don't have logic or reason, so it's not a good analogy. | E.g. you can replace an infinite set of memories by distilling | them into a few bits of knowledge that underpin that given set | of experiences. | jvanderbot wrote: | I don't think an analogy is meant to be factually equivalent, | it is meant to convey meaning. I perfectly understood the | meaning of the parent comment, even if it is technically | inaccurate. | | We aren't trying to understand minds or caches, we're trying | to encourage a practice that has little to do with the inner | workings of either. | ilyazub wrote: | Good point. Reminds me "All models are wrong, but some are | useful"[1]. | | [1]: https://en.wikipedia.org/wiki/All_models_are_wrong | dekhn wrote: | CPUs have logic, and programs can do reasoning. And that's | now how the brain works (if you mean generalization). | orangepurple wrote: | Analogies are almost always flawed but they are powerful | tools for forming strong associative memories. | | They are a starting point for encoding new knowledge in a | custom symbolic language known only to yourself. It is the | basis for all learning. | | Some other major tools for learning are mnemonics and spaced | repetition. | stinos wrote: | Fair point, but on the other hand: I need to format strings and | use basic regular expressions at least a couple of times per | week and the execution performance increase and convenience | from finally having learnt those by heart (simply by using them | enough) is definitely worth it for me and not at all similar to | having to look them up each time. | orangepurple wrote: | We are saying the same thing with different words | lanstin wrote: | Sure but if you use like five languages then the differences | between s.length len(s) and length(s) will blur when at the | beginning of the day you need to refresh the cache for todays | language. | | i could memorize them all but it is less interesting than | reading papers about optimizing algorithms for cloud | economics or other more valuable (to me) ideas. | Jensson wrote: | Why are you using five languages? I mix them up when I | switch, but I rarely work in more than two languages at | once, and keeping two separate isn't that hard. | toast0 wrote: | When I'm working in my preferred environment, I need to | work in its language, but the language/VM is built in | something (usually C), and the kernel I'm running on is | built in something (usually also C), and I might be | making a webpage where I need a bit of Javascript. And | sometimes I need to poke at a shell script or something | that's overgrown shell and is now Perl. And sometimes my | preferred environment isn't really the right fit for the | problem at hand, so I've got to use something else. Oh, | and maybe I need to compile stuff, so here comes Make. | lanstin wrote: | For sure I always have to Google 'make' the first two | hours of using it again. | Macha wrote: | Context switching between Java, SQL, Javascript and a | build scripting language isn't _that_ unusual an | experience. Throw in a templating language there and | you're at 5. | inetknght wrote: | > _Improving your own brain with memories and knowledge is like | greatly increasing the size of a CPU L1 cache_ | | Yup... and as the size of L1 cache grows so does its latency. | Eventually you reach the latency of main RAM and then... wait I | forgot why you increased L1 cache size. Can you just reset it | to "fast" please? | cardanome wrote: | I am on the opposite end of this. The older I get the more I see | the value of rote memorization. | | Just taking the time to actually learn what the standard library | of the programming language you are using provides can | dramatically increase your productivity. The same with important | libraries you are using. Yes, it is too much to memorize | everything but just knowing what actually is there will help you | a lot. You can not search for something you don't know exists. | | I also really love working on solo projects because I tend to | memorize the general shape of the code I am working on. This | makes me so much more productive. I might not remember every | single line of code in detail but will have a pretty clear idea | of the shape of the program. This means I can plan new features | or doing refactors in my head and see if they would work. I don't | need to sit in front of the computer. I can do the hard mental | work while taking a shower or going for a walk and can type in | the code afterwards. | | Anyone else work like this? | quickthrower2 wrote: | I agree after doing a React course that teaches on a | memorization basis (every exercise you get a blank screen, no | docs!). | | However at work I am stumped about _what_ to memorize? At work | I do a bit of everything from new k8s cluster to front-end | optimization. | mattnewton wrote: | Well, memorizing algorithms lets me know what is possible sure, | but memorizing the actual api methods and arguments seems like | a colossal waste of time for my specific circumstances. If it's | possible in one language it should be possible in another. I | haven't ever reused _exactly_ the same stack twice in my | career, so it seems hard to optimize for the exact incantations | rather than lazily find out what is in the library vs community | packages. Looking them up is cheap enough, and I save shower | time for high level thinking about what kinds of programs could | be useful. | onemoresoop wrote: | The problem with rote memorization is that it makes life a pain | when something changes from under your feet, you have to | unlearn and relearn which takes double the effort. However, | it's good to rote memorize more static info and references, | tables of contents and so on. The rest I leave it to use, what | is referenced multiple times becomes permanent. | adam_arthur wrote: | If your code reads like English, you don't need much of a memory. | | A codebase that requires large working memory typically means | it's written poorly. Lacking encapsulation, poor | modularization/separation of concerns, unnecessarily succinct | variable names ___________________________________________________________________ (page generated 2022-09-19 23:00 UTC)