3 ms·

I really like this one: > Documentation is a love letter to your future self This seems like a brilliant way of transcending what feels like a drudge-job, mak

I really like this one: > Documentation is a love letter to your future self This seems like a brilliant way of transcending what feels like a drudge-job, making it into something really meaningful.

tomelders 7y ago
Writing code is also UX. some future user will have to understand it. More often than not, that future user is you.
- ehnto 7y ago
  Which is why: Verbosity is not bloat. Abbreviations are a code smell. I remember encountering a platform in a language before namespacing was introduced in that language, and it had names for the classes like `Platform_Catalog_Model_Product_Simple_Collection`. It looked really silly, but I always knew what I was working with at a glance. It was honestly a really nice developer experience.
snarf21 7y ago
Not that documentation is bad but it is rarely correct. Now you have to spend time trying to match documentation that doesn't match the code you see. I always prefer a different approach. There is no need to document what a function does, that is self evident from stepping through it. The thing that should be included in the code is the WHY, meaning why does this function even need to exist and how does it fit into the architecture? Now an accurate high level architecture diagram and function raison d'etre telling you everything you need to know with much less risk of not having an accurate and up-to-date documentation process.
- mannykannot 7y ago
  > Not that documentation is bad but it is rarely correct. Rarely? I often turn to the documentation to check the capabilities, syntax and semantics of the languages and interfaces that I use. If it were only rarely correct, I would be in trouble. If you are talking about application code specifically, my experience is that documentation is too rarely present to be an issue.
- brianpgordon 7y ago
  > Not that documentation is bad but it is rarely correct. Now you have to spend time trying to match documentation that doesn't match the code you see. It depends on what you mean by documentation. If you mean articles on Confluence or whatever, yeah, that's hopeless. If you mean comments in the code, I couldn't disagree more. I don't buy the common argument that comments easily become inconsistent with the code. I can't imagine changing a line of code and completely ignoring the comment above it, and I'd definitely require a fix if I saw someone else do that in a code review. That's just a ridiculous level of sloppiness. > There is no need to document what a function does, that is self evident from stepping through it. I'm afraid I disagree here too, though again conditionally depending on what you mean. Straightforward logic shouldn't be littered with superfluous comments. But on the other extreme, the fast invsqrt algorithm needs more of a comment than the canonical "what the fuck?" Yes, given weeks of head scratching any arbitrarily-dense block of code will release its secrets, but that's not good engineering. Anyone can build a bridge by dumping a hundred billion dollars of concrete into the bay until it's dry; good engineering is doing it cost-effectively. A well-placed comment in some non-obvious logic can save time for a developer (likely you) every time they interact with it.
aeorgnoieang 7y ago
I like to include (mostly-professional) jokes or humor in my comments and documentation as it's pretty nice to read later.
WhompingWindows 7y ago
Usually I write "why" documentation before code, that way the purpose is clear as I code it and later when I re-read or share it.

I really like this one: > Documentation is a love letter to your future self This seems like a brilliant way of transcending what feels like a drudge-job, making it into something really meaningful.

tomelders 7y ago

Writing code is also UX. some future user will have to understand it. More often than not, that future user is you.

ehnto 7y ago
Which is why: Verbosity is not bloat. Abbreviations are a code smell. I remember encountering a platform in a language before namespacing was introduced in that language, and it had names for the classes like `Platform_Catalog_Model_Product_Simple_Collection`. It looked really silly, but I always knew what I was working with at a glance. It was honestly a really nice developer experience.

snarf21 7y ago

Not that documentation is bad but it is rarely correct. Now you have to spend time trying to match documentation that doesn't match the code you see. I always prefer a different approach. There is no need to document what a function does, that is self evident from stepping through it. The thing that should be included in the code is the WHY, meaning why does this function even need to exist and how does it fit into the architecture? Now an accurate high level architecture diagram and function raison d'etre telling you everything you need to know with much less risk of not having an accurate and up-to-date documentation process.

mannykannot 7y ago
> Not that documentation is bad but it is rarely correct. Rarely? I often turn to the documentation to check the capabilities, syntax and semantics of the languages and interfaces that I use. If it were only rarely correct, I would be in trouble. If you are talking about application code specifically, my experience is that documentation is too rarely present to be an issue.
brianpgordon 7y ago
> Not that documentation is bad but it is rarely correct. Now you have to spend time trying to match documentation that doesn't match the code you see. It depends on what you mean by documentation. If you mean articles on Confluence or whatever, yeah, that's hopeless. If you mean comments in the code, I couldn't disagree more. I don't buy the common argument that comments easily become inconsistent with the code. I can't imagine changing a line of code and completely ignoring the comment above it, and I'd definitely require a fix if I saw someone else do that in a code review. That's just a ridiculous level of sloppiness. > There is no need to document what a function does, that is self evident from stepping through it. I'm afraid I disagree here too, though again conditionally depending on what you mean. Straightforward logic shouldn't be littered with superfluous comments. But on the other extreme, the fast invsqrt algorithm needs more of a comment than the canonical "what the fuck?" Yes, given weeks of head scratching any arbitrarily-dense block of code will release its secrets, but that's not good engineering. Anyone can build a bridge by dumping a hundred billion dollars of concrete into the bay until it's dry; good engineering is doing it cost-effectively. A well-placed comment in some non-obvious logic can save time for a developer (likely you) every time they interact with it.

aeorgnoieang 7y ago

I like to include (mostly-professional) jokes or humor in my comments and documentation as it's pretty nice to read later.

WhompingWindows 7y ago

Usually I write "why" documentation before code, that way the purpose is clear as I code it and later when I re-read or share it.