Hello,

During my regular translation tasks, i've been having alot of a hard time finding certain string to add translations, this is mainly due to the lack of documentation, and, commenting on the code. So i'd like to ask, if it would be possible to all core developers that after the next milestone to at least comment they're code changes/adds properly before calling the task done.

Here are some things i'd like to see in a very near future, all my critics try to be constructive, they are not meant to bash anyone or any of the work done, just trying to improve what i think it's one of the best CMS concepts i've ever seen.

a) code commenting, not doing so, is just pure lazyness, and i'm sorry if i offend anyone, but i see alot of uncommented code, remember, what might seem obvious for you might not for a newly contributer. Proper code commenting should be a priority specially in a group development environment.

b) proper documentation in order to new ppl to understand the code quickly to be able to contribute quickly. Having step a) with a api documentation generator is half way through.

c) a detailed explanation of the inner code, what happens every request, which class is responsable of what in each request, if that class extends other, what functions are called automatically by parents and when etc.

Best regards,

thanks for your improvement suggestions.

in fact we spent a lot of time (and internal budget) on improving documentation and commenting of base-classes in the last two months, getting ready for the 2.2.0 release. if you're looking for a periodically generated API-documentation, head to: http://doc.silverstripe.com/assets/classes/ (linked from most class-documentation in the wiki).

i agree that phpdoc/wiki-documentation should be an integral part of development and our QA-processes - we're slowly getting there. please bear in mind that silverstripe is a quite young product, and has been traditionally developed by a pretty small group of individuals. we're relying on the community to help us out, especially with adding meaningful phpdoc to existing functionality.

I probably have a tendency to hit the wrong or not done stuff the first times i go see something, let me give you an example of something not commented (in code) that could be easily without much effort:

http://doc.silverstripe.com/assets/classes/sapphire/core/EditableFormField.html#filterClause

I could give alot more examples, but i just hit that randomly, a habit i have when programming (and that i enforce when i have to work with more ppl) is to make sure i have a function skeleton ,i use emacs so i just make a macro everytime i make a new function which creates this skeleton automatically, i also have one for classes, and other several snippets i use often:

/**
* TODO - FunctionName
*
* TODO - Description
*
* @param TODO
* @return TODO
*/
function FunctionName()
{
}

that is just pressing some keys, i don't know what editor the devs use, but am sure functionality like this would be easy to mimic.

The above alone, already subconsciously tells the developer that he HAS to document his function.

About regular documentation, userhelp docs are very good, although they need some updating, and internationalization (am sure the community is more than welcome to translate the docs also), the wiki has alot of info but misses a new silverstripe contributer area where it describes sapphire engine, request workflow diagram/description, classes involved in a simple request, and, a few 'tutorials' of things most requested byt the developers (i can remember one right now, adding non cms users and they're handling for example).

I know this is not a priority, i mean, if i put myself in any of u guys position i know it's not a priority, but, sitting here in the other side trying to contribute get's a bit harder.

Unfortunately, i can't volunteer to do everything i think it's needed (which includes everything i spoke here) but i will and i do in what i can.

Best regards,