Your program's limitations:
- What platform/OS it should run on.
- What range of inputs are valid.
- How large an input, memory-wise, it can accept (such as an input file).
- How much memory does it consume.
- Where is its performace bottleneck (file I/O, number crunching).
- What has not been tested (coverage holes).
- The limitations of other modules/libraries it depends on.
How it compares against other well-known programs which perform similar functions (CPAN modules, other freeware, commercial software).
- Advantages: Is it free?
- Disadvantages: Is it slow? Does it have a lousy user interface?
Where it was last night (that's a joke :)
| [reply] |
For any given line or expression in the code, you should know exactly what it does and why it's in there. (I was once going over some code with the student worker who wrote it, and I asked him: "What does this line do?" When he couldn't answer that question, I must confess that I enjoyed giving him a really hard time about it.)
For any given function/subroutine that you either define or invoke in your code, you should know where its usage is documented (parameters, return values, behaviors for error conditions). For functions you have written, this entails that you write documentation for them, or at least know how to extract this information easily from your code. Memorizing all the details about all functions is not required, and is not practical (probably not humanly possible) -- that's why having documentation (and knowing how to get at it) is so important.
As it is with functions/subroutines, so it is also with the inputs and outputs of a given program. This can be a bit daunting when the program is a GUI with lots of flexibility in what the user can do, but even there, it should be possible to describe what the user is expected to provide as input, and achieve as a goal. Such documentation is a courtesy that the programmer owes to the user. | [reply] |