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
smime.p7s
Description: S/MIME cryptographic signature
------------------------------------------------------------------------------ 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=157005751&iu=/4140/ostg.clktrk
_______________________________________________ Synfig-devl mailing list Synfig-devl@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/synfig-devl
