At the office we have a wiki where we keep track of all updates to all projects. It isn’t very structured, which takes away from its usefulness, but I’m fine with that. I’ve developed a simple structure for posting updates, listing the status of the issue, the date, the current location of the changeset, the locations of the lines of code changed, and any other information about the issue.
I do have a problem with how some people (not just in the wiki) document their changes - regarding referencing lines of code. Writing that you changed Line 1165 might be useful, until the next changeset where someone adds 100 lines to the beginning of the file. No one is going to go through the wiki and update your 1165 to 1265, so there has to be a better way!
This is my suggestion, and I have been using it for a day or two.
Syntax:
/path/to/file/file.ext/function_name()/comment
For example:
/test/applied/2008-11-20-gb-001/theme/functions.php/get_username()/Check for errors
This obviously references the code in the function get_username() inside functions.php, near the comment //Check for errors. This way, the code can change shape all it wants, and the reference will stay current.
Comments?
gav
November 21st, 2008 at 1:59 pm
Good idea… until functions change names, or get moved around into a different (possibly better structure), then the comments are useless either way. It is better to write:
functions.php => Check for more errors in get_username()
When you are looking at the subversion logs it tells you the rest of the information anyway… you are using subversion right? I cannot think of a reason to document your code in a wiki when you can use phpdocs to do it automagically, all you have to do is add the comments to the code.
November 21st, 2008 at 8:31 pm
We are using MS Visual Sourcesafe, not subversion. Also, we use a wiki. That’s just how it is. I’ve tried to reason, suggest new project management systems, but everyone is too busy with their projects to change everything. The best I can do is put some kind of structure into my wiki entries.