4 ms·

Code IS documentation!

by edmcnulty101 4y ago

EvanAnderson 4y ago
Like how a recording of a performance is the same as the sheet music.
- edmcnulty101 4y ago
  Haha that's a great analogy. I'm going to use that when someone gives me that BS line that code is documentation.
  - dwringer 4y ago
    Lots of music is performed first, and only later transcribed (often from a recording). In all cases, a music performance contains more data than sheet music (although there's no guarantee that the performer played their sheet music accurately to the page, if they had any). However, in many cases it's much more productive to learn a song by listening to a recording. Paul McCartney famously didn't use sheet music at all. I guess sheet music is like documentation, but just like documentation it's often incomplete, wrong, confusing, misleading, or worse than nothing at all. Sometimes it's the only ground truth we have, such as with classical music where we can't know what the composer truly had in mind, so in cases like that I'd say the sheet music is effectively the source code.
- biofox 4y ago
  Development is like a one-way hash function: a line of code may have been added and structured a particular way for any one of an infinite number of reasons. Without the documentation (the forward mapping) there's no way to exactly predict its intended function, leading to all sorts of misunderstandings further down the line when someone tries to reverse it.
  - throwaway821909 4y ago
    Doesn't need re-explaining but makes me realise we often talk about comments explaining what code does, which leads to "your code should be well-written so it's easy to understand what it does" or "I'm a good developer, I can understand that easily by reading it". But as you say the question is why - people will often be reading existing code because of a bug, so clearly the thought process that created it had a faulty step somewhere.
    - bobthepanda 4y ago
      Really, what people think should go in comments should instead go to commits, which is actually a snapshot of what the author was trying to achieve during a point in time. Inline comments just become out of date or mangled. Commit revisions are the source of truth.
      - biofox 4y ago
        The problem with commit messages is that they quickly get buried in the log, and are difficult to dig up. It's not perfect, but comments stay with the code throughout the versions.
        bobthepanda 4y ago
        git blame will usually give you the last edit of a line, which I find is fairly easy to see the last time it was changed (and then if you want to know how things were done earlier, do the same on its parent commit)
- RajT88 4y ago
  Playing by ear is an amazing skill you can develop. Some people (to name drop a musician: Joe Stump) can hear something once and just play it, note-for-note. But it's a ton easier when you're young, and your brain is malleable.

Code IS documentation!

EvanAnderson 4y ago

Like how a recording of a performance is the same as the sheet music.

edmcnulty101 4y ago
Haha that's a great analogy. I'm going to use that when someone gives me that BS line that code is documentation.
- dwringer 4y ago
  Lots of music is performed first, and only later transcribed (often from a recording). In all cases, a music performance contains more data than sheet music (although there's no guarantee that the performer played their sheet music accurately to the page, if they had any). However, in many cases it's much more productive to learn a song by listening to a recording. Paul McCartney famously didn't use sheet music at all. I guess sheet music is like documentation, but just like documentation it's often incomplete, wrong, confusing, misleading, or worse than nothing at all. Sometimes it's the only ground truth we have, such as with classical music where we can't know what the composer truly had in mind, so in cases like that I'd say the sheet music is effectively the source code.
biofox 4y ago
Development is like a one-way hash function: a line of code may have been added and structured a particular way for any one of an infinite number of reasons. Without the documentation (the forward mapping) there's no way to exactly predict its intended function, leading to all sorts of misunderstandings further down the line when someone tries to reverse it.
- throwaway821909 4y ago
  Doesn't need re-explaining but makes me realise we often talk about comments explaining what code does, which leads to "your code should be well-written so it's easy to understand what it does" or "I'm a good developer, I can understand that easily by reading it". But as you say the question is why - people will often be reading existing code because of a bug, so clearly the thought process that created it had a faulty step somewhere.
  - bobthepanda 4y ago
    Really, what people think should go in comments should instead go to commits, which is actually a snapshot of what the author was trying to achieve during a point in time. Inline comments just become out of date or mangled. Commit revisions are the source of truth.
    - biofox 4y ago
      The problem with commit messages is that they quickly get buried in the log, and are difficult to dig up. It's not perfect, but comments stay with the code throughout the versions.
      - bobthepanda 4y ago
        git blame will usually give you the last edit of a line, which I find is fairly easy to see the last time it was changed (and then if you want to know how things were done earlier, do the same on its parent commit)
RajT88 4y ago
Playing by ear is an amazing skill you can develop. Some people (to name drop a musician: Joe Stump) can hear something once and just play it, note-for-note. But it's a ton easier when you're young, and your brain is malleable.