[mapguide-internals] Improving the Code Base/ General Approach
to Commenting Code / Inline Documentation as a community effort???
traian.stanev at autodesk.com
Thu Mar 19 11:37:13 EDT 2009
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.
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???
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." )
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
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
1) additional level of commit right which only allows comment lines to
2) secondary repository for the comments with an automated merging process
Please comment :)
mapguide-internals mailing list
mapguide-internals at lists.osgeo.org
More information about the mapguide-internals