[mapguide-internals] Improving the Code Base/ General Approach to Commenting Code / Inline Documentation as a community effort???

[Traian Stanev]

Hi UV,

Since you asked for comments... If you send your documentation patches to someone with commit rights, or post them on the mailing list, I'm sure they will be more than happy to check them in. Generally, to get commit rights, you have to submit several viable patches first. Personally (and I don't have a vote on this :) ), I don't think there is need for many levels of commit rights.

I sympathize with your frustration with large amounts of undocumented API. We've all had to deal with stuff like that. In a perfect world, documentation would be complete and up to date, kittens would be roaming free, bandwidth would be infinite, network latency would be zero, and I would be having a quad tequila on a tropical island in the Southern hemisphere. However, this is reality, and I'm not, which works out in your favor -- you have at your disposal, on this mailing list, the people who actually wrote the code with their bare fingers and can answer just about any question about it that you can ask. So while the documentation is not perfect, you have an even better resource. The documentation can improve with time.


Traian


-----Original Message-----
From: mapguide-internals-bounces at lists.osgeo.org [mailto:mapguide-internals-bounces at lists.osgeo.org] On Behalf Of UV
Sent: Wednesday, March 18, 2009 10:09 PM
To: MapGuide Internals Mail List
Subject: [mapguide-internals] Improving the Code Base/ General Approach to Commenting Code / Inline Documentation as a community effort???

Some thoughts!

in order to make sense out of the server source code (which contains 
large amounts of duplicate code) I had to comment most methods 
participating in the call sequences needed for my patch.

It was quite an effort to understand the code enough to be able to 
comment the method functionality.
It would be a waste to throw this away.

As I do not have commit rights I was wondering about the process to 
merge my patches (including the comments) back into the code base.

I think there was no build server with a continous build system and 
embedded testbed which would make this fairly hazzle free.
Is there a peer review process in place or how is this handled?

INLINE DOCUMENTATION & REFACTORING
I believe reading the C++ code is not a very useful way to communicate 
functional details so we should not underestimate
the value of inline documentation in the source code in particular in an 
open source project. (see some of the included OEM sources)

Refactoring and method extraction would be another way to make the code 
more readable but this is admittedly more complex and hard to implement 
without an automated build and test system.
I believe however thats its a good investment into such a large code 
base as it improves maintainabilty a lot as copy paste tends to 
introduce errors after code changes in the copied parts.

In a previous project I worked at a large C++ application and understand 
the missing time and/or reluctance
of most developers to write external documentation which leaves the code 
base as the only means of communicating important details.
I have been hired to set up an automated doxygen based documentation 
system running daily off the repository to improve coding efficiency.
This was the easy part, the hard part is to get the documentation into 
the code base by the developers.
*This is a communal effort.
*
(I hope we are past the times when "Real Programmers don't need 
comments-- the code is obvious." ) 
http://www.pbm.com/~lindahl/real.programmers.html 
<http://www.pbm.com/%7Elindahl/real.programmers.html>

HOW TO IMPROVE INLINE DOCUMENTATION
Do we all agree how important it is for such a project to make it as 
easy as possible to write inline documentation into the code base?

I believe the completeness of inline documentation is a major indicator 
for OS project maturity and therefore the ease of adding comments
is a major factor in helping the community to improve it.
The external API is documented nicely but below that there is a lot 
missing. 
This is wasting a lot of time and results in more frustration than 
necessary when working with this code base.
Slowing down the learning curve has a detrimental effect on the overall 
advances of the project.

So we could think about a way to have different stages of commit rights 
as in the early phase we are more keen on writing the comments
than later when we have commit rights and already understand whats going 
on.

Possible Approaches:
1) additional level of commit right which only allows comment lines to 
be added
2) secondary repository for the comments with an automated merging process

Please  comment :)
_______________________________________________
mapguide-internals mailing list
mapguide-internals at lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/mapguide-internals