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

[UV]

Thanks for pointing out that the mailing list is working well and some 
sort of replacement...
maybe even better when it comes to complex issues.

My point is that it has to be EASY to add inline documentation. The 
easier it is the more its going to happen.

In the moment I am not even sure who to send the patches to??
(probably about 100 lines of comments by now but  its already mixed with 
my changes so too late)
Clearly making patches and posting them is a much more complicated 
process than a controlled submission into a respository with SVN.

Therefore providing a submit filter that lets everyone in a specific 
group simply submit commented lines is just a winner as its easy......
and the user group to use could be even the mapguide-internal mailing 
list users.....

Of course there is nothing like a perfect world .... but there are 
better processes to consider and better tools to use.....
and currently I dont see that happening.

While moving from inhouse development to an Open Source Project I really 
believe its valid to consider a change in the value system 
So it might be worth a thought or two.....

 I am an evangelist when it comes to coding style and inline 
documentation......
I write my comments before I write my code ;-)
and I believe that having suffered yourself is an insufficient excuse 
for letting future developers suffer also.

I did work in the field of CI and automated documentation systems
and
I do offer my support in this field!

here is a link to my resume to show why I am talking like this
http://www.gulp.de/resume/uv.html


Traian Stanev wrote:
> 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
> _______________________________________________
> mapguide-internals mailing list
> mapguide-internals at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>
>