Hello, On Jan 10, 2011, at 6:12 PM, Viktor TARASOV wrote:
> On 10.01.2011 16:01, Viktor TARASOV wrote: >> From: Andre Zepezauer <andre.zepeza...@student.uni-halle.de> >> it's hard to follow all the changes done in the last view days. Here >> some issues I found so far: >> > I do my best, trying to split the changes into the small logical commits. > Your suggestions? >From ohloh.net OpenSC project page: """ Across all C projects on Ohloh, 19% of all source code lines are comments. For OpenSC, this figure is only 11%. This lack of comments puts OpenSC among the lowest one-third of all C projects on Ohloh. A high number of comments might indicate that the code is well-documented and organized, and could be a sign of a helpful and disciplined development team. """ One of the longstanding problems of OpenSC is lack of documentation, both developer (source comments, internal architecture, tutorials on how to add new card drivers other way than copypaste etc) and end-user docs. This is unfortunately quite usual for open source projects, especially for niche project that does not attract a huge crowd of volunteers and where some companies could even sometimes take lack of documentation as a competitive edge. This is not a trivial thing to fix, especially for source code, which is not as "sexy" as end-user documentation. Not that I would want to suggest a "8 meters requirement" [1], something should be done about it. Some ideas that would help 1. Embrace doxygen (or some alternative?) for new comments and for the framework for documenting the source. - Doxygen has been used for some parts of the code before and is a well accepted mature solution. - Documenting internal API will do good for refactoring purposes. - Documented and filtered API could be again exposed to external users in a -dev package. - Require new code comments to be in doxygen format. 2. Use meaningful commit messages, which would allow to track code evolution in a meaningful way by reading the commit history - If it fixes a ticket - include ticket number - If it has a thread on opensc-devel, include a link to the thread start or the most appropriate message in the thread - If the change is non-monotonous (not a "sed replace") or obvious (spelling, compiler warning, whitespace, typo) write a proportional motivation for the change - Not what can be read from single line code change, but what will happen when you observe the functioning of the full software solution. - If it can be referenced to some specification, add a quote or reference to the document. 2. Require a "sensible ratio of comments" in new code commits, which - include motivation for function documentation why a common function can not be used (deviation from standards, etc) - describe the function (maybe dismiss hook functions that are documented centrally in opensc.h) - too much code that will exist as boilerplate without a thing to comment, would be a good sign for a place to improve. Overall, the goal would be to increase the effort needed to figure out "how?" to code right now (not just write code but do some research and refactoring if necessary) and reduce the time needed later to figure out "why?" certain source code exists. Adding a code review system would help, finding people who would be interesting in watchdoging commits and re-writing them (like in a git workflow) with comments would be even better, but I think impossible to achieve at the moment. Thoughts? [1] http://thedailywtf.com/Articles/Very,_Very_Well_Documented.aspx -- @MartinPaljak.net +3725156495 _______________________________________________ opensc-devel mailing list opensc-devel@lists.opensc-project.org http://www.opensc-project.org/mailman/listinfo/opensc-devel
