Making a change set with only comments
Last updated at 3:02 am UTC on 16 October 2006
THe idea is to make it easy for people to help out document the classes and methods we have in the base image by adopting an "express treatment policy" for ChangeSets that only contain new or improved comments for classes and methods.
Step by step:
- Open a changesorter (dual or single) and create a new changeset using "new changeset...". All changes you do from this point on will be "recorded" into this changeset.
- Make changes to only class comments and/or method comments. Keep in mind that:
- Class comments follow different styles. Some explain structure (instance variables) in detail while others explain generally what something is and might even include a small example doit. As long as your comment is either new or vastly better than the one you are replacing - style does not matter much. But try to not repeat information readily available elsewhere.
- When adding or replacing method comments. Try follow the general conventions:
- Comment is one tab indented.
- Sentences begin with capital letter and end with period - and yes, in method comments too. :)
- If you write several sentences, consider keeping down the line length relative to the code's "general width".
- Use one empty line after the comment before the code starts to visually separate the two.
- Do not write method comments for accessors or trivial code.
- Try to describe mainly intent, things that are not obviously learned by glancing at the code and the return value if that is not obvious.
- Do not bundle too many comment changes into the same changeset. Typically use one changeset per class, or at least per "area" that you are commenting. If your changes are not trivially an improvement (for example, you might be rewriting a class comment with a new one and your improvement may not be obvious to some people) then it will be harder to include the other changes if they are all bundled in the same changeset.
- Add a preamble to the changeset explaining shortly what it includes and why. Add your full name to the preamble.
- Rename the changeset to "CommentsOnlyXXXX-yourinitials". The "CommentsOnly" prefix tells us that the cs is "clean" from code. Including your initials is customary for bug fixes etc, and also make sure you have registered them at SqueakMap.
- Compress the changeset using the FileList (adds .gz suffix) and upload the changeset to Mantis under a suitable issue, typically create one first. (Should we do this in any other way??)
- When all the above is done - ask the current Release Team to pick it up and integrate it. :)