On Mon, 28 Apr 2008, Ryan Neufeld wrote: > I was going to email this exclusively to my mentor, xdotx, but I figured > there may be others who have a say. > > I am about to hop into some heavy documentation reading this week, and > frankly, I have never done anything like this before. What advice do you > more experienced programmers have on getting to know a piece of software > through documentation? Is it, say, like reading a book? Studying for an > exam?
Like studying for an open book exam. You don't need to memorise anything
except where to find the information you need.
> Memorization? Trial and error? Playing with code while reading? or a
> mix of all of the above?
Playing existing games would probably be helpful as well.
> My initial idea, and please critique this, is to give the documentation a
> relatively quick read-over, not necessarily consulting with the code
> itself, just the docs. Then, having gotten a taste for it, I want to start
> going over sections of the documentation with actual source code on my
> other monitor, seeing how things are used, etc. From there, I don't know,
> perhaps creating "play" rulesets to toy with, etc. What do you think?
Sounds like a good idea. Another thing to do could be to play minisec (say, on
demo1) and read the parts of the code to see what is happening under the
hood.
> Also, what rules/guidelines exist when it comes to creation of code. What I
> mean is preferred style of formatting, naming conventions, and all that
> jazz.
I generally regard rulesets are separate bodies of code, so you can create
your own and stick to it.
Having said that, I prefer:
- Classes are CamelCase
- Class methods are surlyCaps (ie first letter lower case, caps at start of
words after that)
- Indent is 2 or 4 spaces, no tabs
- opening bracket at the end of previous line, ie:
for(int i = 0; i < 3; i++){
//blah blah
}
- Comments where things are not clear or obvious.
- Use a namespace for you ruleset, just to be safe.
> As for commits, what is required in the comments? I see many commits
> in the logs are generally a line or two for small changes, and a paragraph
> or more for more extensive changes; is this proper?
Yes. The main gist of the changes should be on the first line. After that,
more detail can be given.
> Thanks,
> Ryan (jphr)
Hope this helps.
Later
Lee
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ tp-devel mailing list [email protected] http://www.thousandparsec.net/tp/mailman.php/listinfo/tp-devel
