How should a one-man development shop document their code?

Question

Hi,

please let me first describe my situation. I work in an IT department for a small-to-medium sized industrial-company and basically I'm the only real developer (sometimes a second guy joins in for his own projects). I programm mostly in C#/.net. Of course I only programm for internal need (Intranet, reporting, data-driven apps, some mobile apps, ...).

My question is how should I document my work? It's a highly dynamic environment (the features and bug fixes I implement are tested by me during production, and go live, often within a day. If I technical documentation like MSDN or even overview diagramms those would take me more time to sync than the whole programming process.

Also I feel it's a waste of time because I would be the only one who ever read it.

I do understand that if I get sick, leave, or forget this documentation would be valuable.

PS:well of course you are right - the quesion is how much and how/where.

I try using the XML-docu comments for the public exposed parts but as I'm a believer in self-documenting code the comments mostly restates in plain text what you can read from the method-head itself :(Maybe using the remarks section is the key but if you have 30 lines of code with a 15 line xml-comment in front it just looks dirty

(sorry for posting it here but our firewall rejects JSON :( )

Answer 1

Documentation is useful even if you are the only one that is going to read it. For one thing it forces you to think about the code you are writing from the point of view of sense and structure, and whether or not the design makes sense. Having done so, you are more likely to come up with a correct design, which will last longer and require fewer changes.

Answer 2

Simple answer. With C#, turn on XML documentation. It will warn if you have undocumented public members. Fix the warnings. You will love yourself for it tomorrow.

With that trivial step, you'll get documentation popping up in intellisense while developing. If they actually hire someone else, then you can use something like Sandcastle from Microsoft to generate help files in the MSDN style so they can F1 on framework classes and see.

It takes less than a few minutes, and gives you a reminder of what the the parameters for that method you wrote two years ago actually mean.

Answer 3

At a minimum do try to add class and method documentation, along the lines of JavaDoc (I don't know of a C# alternative), its basically comments that you format in a special fashion, which can be quickly rendered as HTML files, giving you an API-documentation style to your own code.

Answer 4

Do you comment your code? If not, maybe that's enough in your situation, in case you forget what some part of code does/should do. Oh, and turn on XML documentation, as Darren suggested.

Answer 5

Just as well as a big shop.

I learned this as a baby programmer writing RPG/II in 1969: six months after I'd written something, I came back to change it, and had not a clue what I'd been doing. Ever since then, I've commented very heavily.

Answer 6

I've been in the kind of situation you describe, having gone the MicroISV route with a software product I created.

I find (and I am sure I am not alone), that when I return to code a couple of months after I have written it, it is almost as though I am looking at code someone else has written.

So the short answer is that I would document it in the same way as anyone else documents it - the fact that it is a one man shop is irrelevent.

Answer 7

A well written modular code don't need much documentation as its self explanatory. The names of the methods, variables if chosen correctly don't need extra documentation. You need documentation at places where its difficult to know what the code is doing.

Answer 8

First off, the XML Comments on public methods can be valuable, but don't do them 'just because'. I mean a method called 'GetStuffFromDatabase' with the comment 'Gets the stuff from the database' is... well, you get the picture. Still, it's better than nothing and easy to do.

But what I really would do:

• Write unit-tests for your code.

They serve as documentation for other developers (and for yourself). The tests show what exceptions the code returns, how the happy flow goes, the validation etc.

Combine this with well namen and well-factored code and it's pretty much self-explanatory. Write small (2 pages) high-level docs for critical design decision only (explaining mostyl the rational behind choosing the solution).

Other than that, since you point out the environment is pretty dynamic, I personally wouldn't waste time on paper tigers in which you document lots of stuff your code can tell itself.

Answer 9

Even if you're the only one who reads it, you still need to document your code, for your own sanity. You may need to refer back to it 3 years down the road and you will thank your past self for documenting your code properly.

That being said, I think that the best way for me to document code is to actually write the documentation in the code instead of doing double work and re-documenting it in some other document file later. Use something like Doxygen format when documenting and when you need to produce a document later, for clients or bosses, just parse it through Doxygen.

It would also help to have an overall system block diagram. This should be done with the appropriate tools and techniques. UML is useful only if you know how to use it.

Answer 10

Code comments (XML, doxygen..) and unit tests are valuable... for you an also for the programmers that could join/replace you on your projects. But you should also document the usage/principles/technical specs of the software you write, which could be useful for non-programmer/staff that manages/deploys the piece of software you write. You could set up a lightweight wiki (ie dokuwiki) for this purpouse

Answer 11

There's an old programmer's saying (The authour of which is unknown to me ) which states...

Write your code as if the next person to edit it is an axe-wielding manic, who knows where you live.

This is just as relevant when you're the only programmer, as there will be times when you forget what the hell the code is doing, and turn into axe-wielding maniac - and you always know where you live (I hope)

Answer 12

Self-documenting code does NOT mean not writing code comments and documentation! You can't "self-document" things like

• which methods call this method
• which constants exist for parameters
• the bug tracking number that caused a certain line to be necessary

Answer 13

You dont need any

Documentation is a sign that your code is bad make the code easy to read and dont document it.

Time spend on documentation is much better spent on WHY certain things are the way they are not how a method or a few lines work.

Answer 14

Disagree on self document code...

* which methods call this method

right click find all references. Less lines of document = easier to understand the code.

* which constants exist for parameters

too many parameters is bad using variable parameters is often bad as it reduces readability as can be seen by the need to document it. An overloaded method with a good Name which calls the final method with a constant is much better and it conveys exactly what your are trying to do.

* the bug tracking number that caused a certain line to be necessary

This one im ok with but it s not code documentation , but administrative . You coudl for example embed the bug number in your source code checkin.

Note we all get lazy/have dead lines and write bad code in those case some comments are needed.

Regards,

Ben

Answer 15

If you find that documentation takes to long to synchronise with the current code you might want investigate tools that can generate the code from the diagrams or generate diagrams from the code.

For example:

• MS SQL has got Visual Database Diagrams that appear to adjust the tables according to the diagram.

• NetBeans UML plugin has got the ability to generate diagrams and generate code.