Note
A communicable material used to explain some attributes of an object, system or procedure.
I've saved the most important for last, as documentation is itself, just as important as the code which it describes.
When documenting your code, be sure to remember:
- All your documents should be in English.
- Use full sentences.
- Avoid spelling/grammar mistakes.
- Use present tense.
Documentation is placed in tripled double-quoted strings right below what you are documenting.
Documentation with Summary
def Hello():
"""Says "hello" to the world."""
print "Hello, World!"
Hello()
That "docstring" is the least you can do to document your code. It gave a simple summary.
If your docstring spans more than one line, then the quotes should go on their own lines.
You may have noticed that 'Says "hello" to the world.' is not a full sentence. For the first sentence in a summary, you can imply "This member".
Parameters should also be documented.
Parameters
def Hello(name as string):
"""
Say "hello" to the given name.
Param name: The name to say hello to.
"""
print "Hello, $name!"
Hello("Harry")
To read it to yourself, it goes as such: 'Say "hello" to the given name. Parameter name is defined as the name to say hello to.'
This keeps in line with using full sentences. If describing the parameter takes more than one line, you should move it all to a new line and indent.
Long Parameter
def Hello(name as string):
"""
Say "hello" to the given name.
Param name:
The name to say hello to.
It might do other things as well.
"""
print "Hello, $name!"
The same goes with any block.
Here is a list of all the tags that can be used:
Tag |
Description |
---|---|
No tag |
A summary of the member. |
|
This specifies the parameter |
|
This describes what the method returns. |
|
This provides descriptive text about the member. |
|
Gives a reason why an |
|
Provides an example. |
|
Includes an excerpt from another file. |
|
Describe a required Permission. |
|
Lets you specify the reference that you might want to appear in a See Also section. |
And a list of inline tags:
Tag |
Description |
---|---|
|
Bullet list |
|
Numbered List |
|
Provides an inline link to a reference. e.g. <int> or <string> would link. |
|
References to a parameter of the method. |
Here's some examples of proper documentation:
Documentation example
import System
class MyClass:
"""Performs specific duties."""
def constructor():
"""Initializes an instance of <MyClass>"""
_rand = Random()
def Commit():
"""Commits an action."""
pass
def CalculateDouble(i as int) as int:
"""
Returns double the value of [i].
Parameter i: An <int> to be doubled.
Returns: Double the value of [i].
"""
return i * 2
def CauseError():
"""
Causes an error.
Remarks: This method has not been implemented.
Raises NotImplementedException: This has not been implemented yet.
"""
return NotImplementedException("CauseError() is not implemented")
def DoSomething() as int:
"""
Returns a number.
Example: Here is a short example:
print DoSomething()
Returns: An <int>.
See Also: MakeChaos()
"""
return 0
def MakeChaos():
"""
Creates Chaos.
Include file.xml: Foo/Bar[@id="entropy"]
Permission Security.PermissionSet: Everyone can access this method.
"""
print "I am making chaos: $(_rand.Next(100))"
def Execute():
"""
Executes the protocol.
Does one of two things,
# Gets a sunbath.
# Doesn't get a sunbath.
"""
if _rand.Next(2) == 0:
print "I sunbathe."
else:
print "I decide not to sunbathe."
def Calculate():
"""
Does these things, in no particular order,
* Says "Hello"
* Looks at you
* Says "Goodbye"
"""
thingsToDo = ["I look at you.", 'I say "Hello."', 'I say "Goodbye."']
while len(thingsToDo) > 0:
num = _rand.Next(len(thingsToDo))
print thingsToDo[num]
thingsToDo.RemoveAt(num)
[Property(Name)]
_name as string
"""A name""" // documents the property, not the field
Age as int:
"""An age"""
get:
return _rand.Next(8) + 18
_age as int
_rand as Random
This should give you a good view on how to document your code. I think Dick Brandon said it best:
Quote
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.