Hi Jason,
from my point of view a good code comments is crucial for the usability and
maintenance of it. We had have discussions about code style too (not only
comments but how to indent, variables and function naming, separate with
empty lines, or bracketing).
The problem with the strict rules on that (code format and comments) is
that there must be someone that supervises the those rules before approve
the patch or branch to be merged into main code. Sincerely, in our coding
history, our main preoccupation was that *someone codes something* because
the lack of people working to improve the program was our standard over the
years. It could explain what you have found on the code.
That's a problem of the community contributed programs. If you want to keep
readability of the code you need someone that doesn't allow to merge code
that doesn't follow the standards. And some times it is not a good idea
because you can loose the opportunity of enroll a new coder. Also, that
supervision needs time, that we have so few.
Your draft document looks quite good to me to start with. I can bet that
our current coding heroes would do their best to follow up those rules.
Only by commitment we could settle them by our standard.
Let's see ow it goes.
Also I would like to take your step and comment a general issue with the
coding patches. We haven't got a standard set of test to validate new code.
It is very frustrating that when you adopt new functionalities other
program features are ruined. That is specially important when code changes
affects the core of the program because the impact is in every place. Also,
upgrade libraries has its problems and we don't have a way to detect
drawbacks once you upgrade some library. In some point we should start to
take that seriously because that, mixed with the lack of comments would
make the program impossible to debug or unusable.
Thanks for take your time on the problem.
2014-11-27 21:56 GMT+01:00 Jason C. McDonald jcmcdon...@mousepawgames.com:
Hi everyone,
My team and I have been working on getting acquainted with the Synfig
source code (we're currently in synfig-core), and it is a bit tricky, even
with the API docs. May I suggest implementing a commenting standard? This
is something I've learned from having written a game core and a language,
and collaborating with others on it: good comments aid every aspect of
programming, especially in a large project.
At MousePaw Games, I am in the process of implementing a commenting
standard called CSI (Comments Showing Intent). The basic premise is that
every logical step in the code is accompanied by a plain-language comment
describing the logic. The end goal is that the comments pass the CSI
Test, in that the code could theoretically be reconstructed in any
programming language using only the comments. (This standard should also be
able to merge seamlessly with the doxygen standard the API docs need.)
My own early experiments with this standard have been encouraging. I
implemented an early version of the CSI standard in the Python source code
for my project, Redstring (it's on Sourceforge), and the result was that I
could debug and optimize code quicker, and that other people reading the
code could quickly understand what I was doing. It didn't actually take
much longer to do, as the process of CSI commenting sped up my workflow, by
helping me keep track of what I was doing, and where I was going,
especially with complex logic.
I have already instructed my team to start commenting all of Synfig's code
in our fork, as we figure out what things do. However, I wanted to propose
the CSI standard here, especially since ya'll know Synfig's code better
than we do right now. I'm very much open to input on the standard, as it is
a work in progress.
Again, my thought is this: if Synfig were CSI-commented, the code and API
docs would be more readable, giving us all of the benefits I mentioned
above. Going back and commenting everything right now would be completely
impractical, but if we all could CSI-comment code as we write or review it,
I believe it would make a huge difference.
I have a .PDF of the CSI standards draft, but I don't think I can attach
it here. You can find it at the following link:
http://mousepawgames.com/downloads/csistandard-draft1.pdf
I really look forward to your input on this.
--
Sincerely,
Jason C. McDonald
CEO, Lead Developer
MousePaw Games
Visit Us Online: www.mousepawgames.com
Call Us: 208-557-GAME
--
Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
from Actuate! Instantly Supercharge Your Business Reports and Dashboards
with Interactivity, Sharing, Native Excel Exports, App Integration more
Get technology previously reserved for billion-dollar corporations, FREE
http://pubads.g.doubleclick.net/gampad/clk?id=157005751iu=/4140/ostg.clktrk
