5 ms·

Well written software should generally be able to double as documentation.

angersock 12y ago
Even the cleanest code will only ever tell you how something is done, and not why. The best-factored simply-named controller source or whatever else will not, in isolation and without documentation, ever tell you why we are asking the computer to do the things it does. The problem with this is that somebody (rightly or wrongly) will see the code one day, and infer what they think it is doing, and change it, and break things elsewhere in the world. If you don't want that to happen, you are forced to only ever write code that matches the exact logic of what already exists--and because you, rockstar ninja cowboy that you are, don't have any documentation including business use cases or logic for a particular hack or inelegance, you must then look on and only make the mildest of changes to the sacred monolith. Or, you know, you could document your projects and software like a real engineer, and others can later check that they can make changes with impunity--or even better, throw away chunks of unneeded code wholesale because their time is (according to the docs!) past. EDIT: This whole "The code is the documentation hurrrr" meme is really annoying--it can only express the hows and not the whys. There is more to software than simply the steps the computer takes to transform data. If there wasn't, we'd still be using assembly and Perl every day.
figglesonrails 12y ago
Just no. Well-written software (i.e. clean code, clear functions) is great and a joy to work with, but is absolutely not a substitute for documentation. Public APIs are double-triple-extra not exempt by merely being well-written, especially not C/C++ APIs, which have complex meta-details like "is this thread-safe?", "does this allocate memory?", "can I call this twice using the same object?", etc. I get that if code is clear enough, it should be self-documenting. That alleviates the need to write as many comments. //Comments//. It's not a user manual. It's not an explanation of architecture. It's not a help guide. It's not an example of how to use it. It's not best practices. It's not how to write a plugin for your system. It's not an explanation of why the software is needed or where it fits into the business's plan. It's. Just. Code. I've inherited enough undocumented code to take new stance: if I quit tomorrow and people are unable to train a new person to fully understand my code without me to train them, then I'm doing it wrong. "Wizards" are also liabilities.
- scrabble 12y ago
  Ok, let's say that the code can double as documentation (which is what I stated), and not that the code doubles as all of the documentation. The code should be able to provide you with the how and the why (supplied with proper testing that covers planned use cases, and comments when testing and code are insufficient.) When code is well written it will answer a lot of questions, I encounter this almost daily when reviewing code. What code is not is a manual or instructions on plugin writing, etc. You are right on the money there. It's also not API documentation, again, right on the money.

Even the cleanest code will only ever tell you how something is done, and not why. The best-factored simply-named controller source or whatever else will not, in isolation and without documentation, ever tell you why we are asking the computer to do the things it does. The problem with this is that somebody (rightly or wrongly) will see the code one day, and infer what they think it is doing, and change it, and break things elsewhere in the world. If you don't want that to happen, you are forced to only ever write code that matches the exact logic of what already exists--and because you, rockstar ninja cowboy that you are, don't have any documentation including business use cases or logic for a particular hack or inelegance, you must then look on and only make the mildest of changes to the sacred monolith. Or, you know, you could document your projects and software like a real engineer, and others can later check that they can make changes with impunity--or even better, throw away chunks of unneeded code wholesale because their time is (according to the docs!) past. EDIT: This whole "The code is the documentation hurrrr" meme is really annoying--it can only express the hows and not the whys. There is more to software than simply the steps the computer takes to transform data. If there wasn't, we'd still be using assembly and Perl every day.

figglesonrails 12y ago

Just no. Well-written software (i.e. clean code, clear functions) is great and a joy to work with, but is absolutely not a substitute for documentation. Public APIs are double-triple-extra not exempt by merely being well-written, especially not C/C++ APIs, which have complex meta-details like "is this thread-safe?", "does this allocate memory?", "can I call this twice using the same object?", etc. I get that if code is clear enough, it should be self-documenting. That alleviates the need to write as many comments. //Comments//. It's not a user manual. It's not an explanation of architecture. It's not a help guide. It's not an example of how to use it. It's not best practices. It's not how to write a plugin for your system. It's not an explanation of why the software is needed or where it fits into the business's plan. It's. Just. Code. I've inherited enough undocumented code to take new stance: if I quit tomorrow and people are unable to train a new person to fully understand my code without me to train them, then I'm doing it wrong. "Wizards" are also liabilities.

scrabble 12y ago
Ok, let's say that the code can double as documentation (which is what I stated), and not that the code doubles as all of the documentation. The code should be able to provide you with the how and the why (supplied with proper testing that covers planned use cases, and comments when testing and code are insufficient.) When code is well written it will answer a lot of questions, I encounter this almost daily when reviewing code. What code is not is a manual or instructions on plugin writing, etc. You are right on the money there. It's also not API documentation, again, right on the money.