13

I'm a hobbyist programmer (with no formal education) looking to start doing small freelance jobs. One of the things that hobbyist programmers can get away with that those with a "real" job can't is lack of documentation. After all, you wrote it so you know how it works.

I feel a little silly asking because it seems like such a basic thing, but how do I document my code?

  • How should it be formatted?
  • How should it be presented? (HTML pages? LaTeX?)
  • What does/doesn't need to be documented?

...And maybe more specifics I haven't thought of.

I mostly program in PHP but also C#.

Improve this question
3
  • 1
    Please specify which language you want to document, the standards and tools vary between languages.
    – Eran Galperin
    Mar 2, 2011 at 2:54
  • 1
    Start with this: What was your software supposed to solve/do? Document the steps on how it does that first and foremost.
    – Sergio
    Mar 2, 2011 at 3:25
  • Please find existing code in existing open source projects. Please read that existing code. Then compare it with yours. Finally, after doing that, please ask specific questions based on the code you found.
    – S.Lott
    Mar 2, 2011 at 3:28

6 Answers 6

Reset to default
11

You should document:

  • the intent, the why;

and

  • what may not be obvious, the how.

Why did you optimise this bit, what exactly is that shortcut for, what is the result you expect, what's the requirement, the reason for it being there in the first place, where does this data get sent to, where do you get the input from, if this is multi-threaded, explain the model, if there is a database, explain the schema, the links, why...

Do not document the obvious. As to presentation there are many many ways to do this. I personally like inline comments (I'm an older kind of programmer and we did not have fancy tools back then - plus I just find it simple and straightforward). If you want something fancy, make sure it does not consume too much of your time or you'll very likely soon abandon it.

Improve this answer
1
  • 2
    Intent is often the most useful thing, I can look at code and understand what it does, but understanding why the developer did it that way can be very useful.
    – Zachary K
    Mar 2, 2011 at 11:19
13

Read some of your own code you wrote 2 or more years ago.

Ask yourself what types of things are unclear, and leave you scratching you head upon reading. Those types of things (whatever they are, they will be different for different programmers) are what you want to start documenting first on any new code you develop, or old code you rewrite/reuse. Any formatting that slows down your understanding, change.

Or else, in 2 years...

Improve this answer
8

One thing you should include is the dependencies. If a function relies on something from over there then document what it is, where over there is, and why.

Improve this answer
3

Since you're using PHP, PHPDoc would be a good place to start. You can build your API documentation inline in the source and then use the same format to write tutorials and user documentation. You'll also get some flexibility as far as output format.

Improve this answer
2

I always start writing code by writing my comments first. Describe the flow of the program, and you'll start realizing what needs to be commented, and what doesn't. After you've started writing the code you embellish the parts that need additional explanation, and refine the parts that are self documenting.

After each class, function, or method is complete, I go back and add comments for a document generator like doxygen or PHPDoc. This will get you the actual API documentation.

Depending on who consumes my code, I'll write a formal description of operation document in either LaTeX or Word.

Improve this answer
1

Doxygen covers most languages. You'll have to spend some time understanding the syntax, but the big issue is what to document. Treat each function as a black box. Document what goes in and what goes out. Document what errors it traps, whether args can be null, whether it can return a null.

Remember, in only a few months you won't be able to figure out what the heck a function does. You are just saving yourself time.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.