Best practices for software development documentation
March 12, 2013 6:06 PM Subscribe
I do some developery-type stuff at work and the more complicated it gets, the less organized I am. I often find myself wondering why I did this or that or what I was trying to accomplish with it. I reuse a lot of the same functions and bits of code but I don't have a good system of keeping track of them. I know about commenting within code, and I do that, but I'm looking for a larger system of general best practices more than a specific solution.
I'm the only one who works on 95% of the stuff I'm doing so these notes are mostly for me right now, but later on it will be very important to be able to communicate Why Things Are The Way They Are and What To Do.
I'm the only one who works on 95% of the stuff I'm doing so these notes are mostly for me right now, but later on it will be very important to be able to communicate Why Things Are The Way They Are and What To Do.
Look at the facility of the language you use. Perl, ruby and Java all have systems that turn inline comments with certain tags into web pages or such. But largely there is an element of self discipline in keeping the habit going.
posted by sammyo at 6:36 PM on March 12, 2013
posted by sammyo at 6:36 PM on March 12, 2013
You are using version control, right? If not, start. If you're starting fresh, git is probably the best choice. Start committing things. Make small commits with descriptive messages.
The best documentation then is the commit messages. It's easy to see a diff of what changed, and since you commit often it's manageable chunk. You've also just linked related changes to different files by the fact that they're committed together.
posted by unix at 6:39 PM on March 12, 2013 [5 favorites]
The best documentation then is the commit messages. It's easy to see a diff of what changed, and since you commit often it's manageable chunk. You've also just linked related changes to different files by the fact that they're committed together.
posted by unix at 6:39 PM on March 12, 2013 [5 favorites]
You will find a lot of very fierce opinions on this kind of thing.
You don't mention what language you're writing, but most modern languages have a convention for writing interface-level documentation - i.e., here is what this function takes and what it returns, or here is what this class does and how it is used, what its individual method calls are, etc. I find that writing this stuff - documentation for a potential user of your code - often does more for me later than line-by-line comments within a chunk of code.
Here's something very simple I wrote ages ago. The documentation is kind of sloppy - the whole thing is, really - but if I need to revisit it, it tells me what it's for and what the moving pieces do. There's a standard format for documentation blocks like this in PHP code, called phpdoc, which that at least loosely follows. It can be extracted from your source using command line tools. If you figure out the equivalent thing for the code you're using and look for examples, you'll have a better idea of how people handle these problems.
The Perl community tends to be pretty good at this stuff - you could do far worse than looking at how popular modules on CPAN are documented, and perldoc is generally a model of clarity and organization.
posted by brennen at 6:39 PM on March 12, 2013
You don't mention what language you're writing, but most modern languages have a convention for writing interface-level documentation - i.e., here is what this function takes and what it returns, or here is what this class does and how it is used, what its individual method calls are, etc. I find that writing this stuff - documentation for a potential user of your code - often does more for me later than line-by-line comments within a chunk of code.
Here's something very simple I wrote ages ago. The documentation is kind of sloppy - the whole thing is, really - but if I need to revisit it, it tells me what it's for and what the moving pieces do. There's a standard format for documentation blocks like this in PHP code, called phpdoc, which that at least loosely follows. It can be extracted from your source using command line tools. If you figure out the equivalent thing for the code you're using and look for examples, you'll have a better idea of how people handle these problems.
The Perl community tends to be pretty good at this stuff - you could do far worse than looking at how popular modules on CPAN are documented, and perldoc is generally a model of clarity and organization.
posted by brennen at 6:39 PM on March 12, 2013
I cannot second unix hard enough. Also, document your tests, especially if you're using a test framework that reads like code rather than words. I often find my commit messages and tests more useful than my docstrings. (Maybe this means my comments need work!)
posted by ecmendenhall at 7:33 PM on March 12, 2013
posted by ecmendenhall at 7:33 PM on March 12, 2013
A simple thing that works well for me is to have a plain text file in the same folder as the program source to contain my notes to myself. Then every time I commit the folder to subversion (or whatever you decide to use) I can not only diff the program modules but also diff my notes. I will have a list of things I don't want to forget to do, a list of obscure minor bugs needing to be fixed, my plan for how to evolve the design, etc.
posted by forthright at 7:44 PM on March 12, 2013
posted by forthright at 7:44 PM on March 12, 2013
Response by poster: I guess I should have gone into more detail about what I actually do, since all of these answers are over my head and/or not applicable.
Right now I'm using SharePoint as a front end for several Access databases, which is not the most perfect or elegant thing in the world, but it's what I have to work with. So I'm creating lots of queries and reports and custom web forms and stuff and it's getting overwhelming remembering what I put where and why. There is some code, too, like SQL and jQuery and vba, but it's not one self-contained thing.
posted by desjardins at 8:40 PM on March 12, 2013
Right now I'm using SharePoint as a front end for several Access databases, which is not the most perfect or elegant thing in the world, but it's what I have to work with. So I'm creating lots of queries and reports and custom web forms and stuff and it's getting overwhelming remembering what I put where and why. There is some code, too, like SQL and jQuery and vba, but it's not one self-contained thing.
posted by desjardins at 8:40 PM on March 12, 2013
I've had luck setting up a private or team-specific wiki: the ad-hoc nature of the kind of coding you're doing may lend itself to that kind of structure. You just have to remember to throw the usefull stuff in periodically. Evernote or one note with robust tagging may work well for you as well.
posted by jenkinsEar at 8:56 PM on March 12, 2013
posted by jenkinsEar at 8:56 PM on March 12, 2013
Along with the recommendations for using version control, I'd say: delete old code! It's in the version repository already, no reason to leaving it hanging around in your working/production copy.
It confuses future maintainers to see a ton of files in the project that are no longer used. Having tons of code commented out also makes it really hard to grep/search the base and find relavent information easily.
posted by sbutler at 10:23 PM on March 12, 2013
It confuses future maintainers to see a ton of files in the project that are no longer used. Having tons of code commented out also makes it really hard to grep/search the base and find relavent information easily.
posted by sbutler at 10:23 PM on March 12, 2013
I'm more of a unix guy myself (ha!), so I'm not familiar with how sharepoint/access/vba projects are structured, but it really sounds like version control is the answer.
Suppose you want to add a report for revenue from international shipments, broken down by country. I imagine you have a file with a bunch of sql statements, and maybe a file for some reports, and a file for each web form. With version control you'd edit or "checkout" (depending on what you use) the files as you change them, then when you're done you can commit them with a message (e.g. "Add international revenue report for accounting"). That message along with the diffs of what you changed is way more valuable than most other forms of documentation.
It may take a little while to wrap your head around the concept of version control, but think of it as a long-term investment.
I'm mildly skeptical of wikis for code documentation. They're good for documenting processes (i.e. how to set up a new development environment, how get code to production, etc), but not for things that are tightly coupled to code. It becomes way to easy to change something and not update the docs, and probabilistic documentation is incredibly annoying.
As for what to use? I'd suggest whatever best integrates with your IDE, as long as it's not cvs. If you must, svn is really a much better choice, and with TortoiseSVN it integrates fairly well into windows. Any form of version control is better than none.
posted by unix at 10:38 PM on March 12, 2013
Suppose you want to add a report for revenue from international shipments, broken down by country. I imagine you have a file with a bunch of sql statements, and maybe a file for some reports, and a file for each web form. With version control you'd edit or "checkout" (depending on what you use) the files as you change them, then when you're done you can commit them with a message (e.g. "Add international revenue report for accounting"). That message along with the diffs of what you changed is way more valuable than most other forms of documentation.
It may take a little while to wrap your head around the concept of version control, but think of it as a long-term investment.
I'm mildly skeptical of wikis for code documentation. They're good for documenting processes (i.e. how to set up a new development environment, how get code to production, etc), but not for things that are tightly coupled to code. It becomes way to easy to change something and not update the docs, and probabilistic documentation is incredibly annoying.
As for what to use? I'd suggest whatever best integrates with your IDE, as long as it's not cvs. If you must, svn is really a much better choice, and with TortoiseSVN it integrates fairly well into windows. Any form of version control is better than none.
posted by unix at 10:38 PM on March 12, 2013
Oof.
I am guessing, from my decaying memories of working with Access and friends, that a lot of the advice here, while useful in the general case, may be difficult to apply in this context.
That said, I bet there are lot of people who have more relevant experience than some of us Unix nerd types. Maybe you could ask a mod to put "SharePoint" specifically in your title to help snag some?
(Does it even work like that? I have asked exactly 2 questions here, and can't remember what you can edit after posting. Anyway.)
posted by brennen at 11:26 PM on March 12, 2013
I am guessing, from my decaying memories of working with Access and friends, that a lot of the advice here, while useful in the general case, may be difficult to apply in this context.
That said, I bet there are lot of people who have more relevant experience than some of us Unix nerd types. Maybe you could ask a mod to put "SharePoint" specifically in your title to help snag some?
(Does it even work like that? I have asked exactly 2 questions here, and can't remember what you can edit after posting. Anyway.)
posted by brennen at 11:26 PM on March 12, 2013
I write code for APIs for a living. Here's what I do:
1. I write the snippet in-line1, because CODE NOW!
2. Then I inevitably regret it and refactor it into a private method within the class
3. Then I consider refactoring it and the surrounding functionality into its own class or suite
4. Then I consider making sections of that suite public and may refactor it further to have the appropriate balance of abstraction and extensibility.
All of this is kept in source control. Source control is a database, but more of a repository so search doesn't exist in reasonable ways (yet).
The most important part is step 3 - in step 3 your are formalizing the packaging of the code and that helps make it an entity.
1 don't do this
posted by plinth at 3:37 AM on March 13, 2013
1. I write the snippet in-line1, because CODE NOW!
2. Then I inevitably regret it and refactor it into a private method within the class
3. Then I consider refactoring it and the surrounding functionality into its own class or suite
4. Then I consider making sections of that suite public and may refactor it further to have the appropriate balance of abstraction and extensibility.
All of this is kept in source control. Source control is a database, but more of a repository so search doesn't exist in reasonable ways (yet).
The most important part is step 3 - in step 3 your are formalizing the packaging of the code and that helps make it an entity.
1 don't do this
posted by plinth at 3:37 AM on March 13, 2013
If you can't fit code into a library (which can be a catch-all VBA module) in a reasonable way, you can create an account on Github and create gists, which can be private or public and are searchable.
posted by ignignokt at 5:13 AM on March 13, 2013
posted by ignignokt at 5:13 AM on March 13, 2013
As others have said, three major things:
1) Definitely use version control if you aren't already. I programmed for 10+ years at places with a change management team and never had to set up version control. In my current job they had nothing and I had to set up svn, a wiki, and a ticketing system. Wasn't hard at all and it's great to know what changes were made and when. Probably use git which seems to be all the rage. We use TortoiseSVN (free) on dev boxes and VisualSVN Server (has a free version) to host the repository. We also use RedGate SQL Source Control for the databases themselves, but that's not free. I love it though.
Another benefit of setting up version control is that it forces you to organize all the code you're written. We do something like:
trunk\
\backendsystems (services etc)
\Components
\DataAccess
\ThirdParty (various libraries)
\Tools (random console apps, etc.)
\Web
2) Code comments. I frequently have to beat developers with a stick to get them to write good comments. Frankly I think auto-generated code docs are a waste of time if they just tell you that class A inherits from class B, or that class B has this list of methods ... I want to know in a human-readable way what the code is for, why I might use it, etc. We use C# and we document public methods and classes. Often the class comments are a friendly rundown of what kind of stuff is in the class and why it's useful.
3) Wiki. We use Confluence and it rules. I haven't written a Word doc other than my resume in like 6 years. You can get a 1-10 user download (need a server though) for $10. The wiki is for bigger picture stuff ... how the components fit together, design notes, Visio diagrams, etc. If you get in the habit of putting everything you learn on there it'll save your life, especially if you have a million small projects going. You can make a simple page with a few notes in a minute or two and add to it later. More importantly, you can quickly search for information instead of trying to remember where it is on the company share drive.
Also for sure keep very code-specific notes in the code and not in some other document. Documentation gets out of date really quickly and syncing it with the code is a drag.
Good luck!
posted by freecellwizard at 6:47 AM on March 13, 2013 [1 favorite]
1) Definitely use version control if you aren't already. I programmed for 10+ years at places with a change management team and never had to set up version control. In my current job they had nothing and I had to set up svn, a wiki, and a ticketing system. Wasn't hard at all and it's great to know what changes were made and when. Probably use git which seems to be all the rage. We use TortoiseSVN (free) on dev boxes and VisualSVN Server (has a free version) to host the repository. We also use RedGate SQL Source Control for the databases themselves, but that's not free. I love it though.
Another benefit of setting up version control is that it forces you to organize all the code you're written. We do something like:
trunk\
\backendsystems (services etc)
\Components
\DataAccess
\ThirdParty (various libraries)
\Tools (random console apps, etc.)
\Web
2) Code comments. I frequently have to beat developers with a stick to get them to write good comments. Frankly I think auto-generated code docs are a waste of time if they just tell you that class A inherits from class B, or that class B has this list of methods ... I want to know in a human-readable way what the code is for, why I might use it, etc. We use C# and we document public methods and classes. Often the class comments are a friendly rundown of what kind of stuff is in the class and why it's useful.
3) Wiki. We use Confluence and it rules. I haven't written a Word doc other than my resume in like 6 years. You can get a 1-10 user download (need a server though) for $10. The wiki is for bigger picture stuff ... how the components fit together, design notes, Visio diagrams, etc. If you get in the habit of putting everything you learn on there it'll save your life, especially if you have a million small projects going. You can make a simple page with a few notes in a minute or two and add to it later. More importantly, you can quickly search for information instead of trying to remember where it is on the company share drive.
Also for sure keep very code-specific notes in the code and not in some other document. Documentation gets out of date really quickly and syncing it with the code is a drag.
Good luck!
posted by freecellwizard at 6:47 AM on March 13, 2013 [1 favorite]
One other thing - if you have or can get a ticketing system (we use Jira), you can usually hook that up to your source control. We do all kinds of crazy one-off stuff here and the process is like this:
1) some team needs us to create some crazy one-off tool and emails us.
2) create a ticket in Jira explaining what they want.
3) keep notes in there about what we're making.
4) on code commits, put the ticket ID in the comment.
5) free svn plugin to Jira associates the ticket and code commit.
6) quick wiki doc explaining what the new tool is for. Reference ticket id in the wiki page.
7) Link ticket to wiki doc.
Then a year later when I can't remember what the hell this tool is (more like 2 months now that I'm old), I search the wiki and from there I can go re-read the ticket, etc.
posted by freecellwizard at 6:53 AM on March 13, 2013 [1 favorite]
1) some team needs us to create some crazy one-off tool and emails us.
2) create a ticket in Jira explaining what they want.
3) keep notes in there about what we're making.
4) on code commits, put the ticket ID in the comment.
5) free svn plugin to Jira associates the ticket and code commit.
6) quick wiki doc explaining what the new tool is for. Reference ticket id in the wiki page.
7) Link ticket to wiki doc.
Then a year later when I can't remember what the hell this tool is (more like 2 months now that I'm old), I search the wiki and from there I can go re-read the ticket, etc.
posted by freecellwizard at 6:53 AM on March 13, 2013 [1 favorite]
This thread is closed to new comments.
posted by michaelh at 6:15 PM on March 12, 2013