Alfresco Coding standards
108 views
Skip to first unread message
Peter Löfgren
Oct 14, 2012, 4:22:16 AM10/14/12
to alfresco-techn...@googlegroups.com
Hi,
I've been looking for clear and easy to follow Alfresco Coding standards. What I've found this far is
Only mentions Java. Set standard for indentation to 4 spaces, but all(?) other files in Alfresco source use 3 spaces. This is the only document mentioning number spaces for indentation, so even it it mentions only Java, this sets the wrong precedence.
Is it only for version 3.0?
This is external to Alfresco, but one of the better overviews.
Why is this important?
As the number of developers and addons published increase, I think that a good Coding standards is essential. Think github, forking and contributing. Or contributing patches for Alfresco bugs.
I'm sure there must be something better available, new Alfresco employee developers must have something better than this to follow to set up their initial environment. Maybe this can be shared?
For example, in Eclipse you can export the Formatter used for Java and Javascript. Can some Alfresco employee export this and attach to the wiki? This way you get a quick and setup that conforms to Alfresco coding standards.
Also add standards for formatting of xml, ftl, css, and possibly other files if applicable. In the wiki have the master Coding_Standards document reference each kind of file, some may not need a separate file (like for java and javascript that has lots of info), put them into the master page, or group them into a separate page.
Also in some page add good plugins to use for Eclipse, may not belong to Coding Standards. But some do help you as a developer to follow standards. Like this (http://propedit.sourceforge.jp/index_en.html) properties editor that helps with saving the properties files in correct format for non ascii-characters.
Cheers,
Peter Löfgren (Loftux)
Richard Esplin
Oct 17, 2012, 8:00:19 PM10/17/12
to alfresco-techn...@googlegroups.com
Making it easier to develop solutions on top of Alfresco is a big focus for us. That includes us making it easier for new community members to learn the process. Internally we call it "developer ergonomics", and we hope you have started to see the results of these efforts and that our pace will accelerate.
Our general approach is to not mandating technology choices, platforms, languages, tooling or development processes and standards to third party developers. Unfortunately we have to make a few requirements in order to deal with the realities of the platform, but we are removing those limitations whenever possible.
However we agree that coding standards and conventions can help with code re-use and participation within the Alfresco community. We also agree that there should be a place for community members to formulate best practices and swap IDE specific tips.
Interestingly, our engineering team uses the wiki pages you mentioned as their style guide. We don't use any more detailed style guide internally.
"Certainly, it's terse, but it gets the main points across regarding the mechanics. Most of our coding standards are defined by the normal Java conventions linked from the first paragraph on our wiki page. We deviate from those in only a couple of small ways, which is why our page seems quite brief."
You make some good suggestions, so here is what I have done:
* Update the "Coding Standards" page with clarifications and other information from our internal conversations that were prompted by your post.
* Lock that page from external edits, since the content should be determined by the engineering team.
* Rename "3.0 JavaScript Code Standards" to "JavaScript Code Standards"
* Create a separate page for conversations around community coding standards. It is called "Community Coding Standards".
* Rather than defining standards in detail, perhaps it would be quicker and more useful to build a list of "best practice" examples of each relevant file type and packaging style. I'll start a place for a list on the wiki page.
I encourage everyone on this list to update the Community Coding Standards page with your suggestions and tips. That goes for all the wiki pages. The official documentation is produced by the engineering team, but anyone can edit the wiki and we hope that you do.
Thank you for raising the issue Peter. I look forward to continuing the discussion at DevCon.
Richard
Our general approach is to not mandating technology choices, platforms, languages, tooling or development processes and standards to third party developers. Unfortunately we have to make a few requirements in order to deal with the realities of the platform, but we are removing those limitations whenever possible.
However we agree that coding standards and conventions can help with code re-use and participation within the Alfresco community. We also agree that there should be a place for community members to formulate best practices and swap IDE specific tips.
Interestingly, our engineering team uses the wiki pages you mentioned as their style guide. We don't use any more detailed style guide internally.
"Certainly, it's terse, but it gets the main points across regarding the mechanics. Most of our coding standards are defined by the normal Java conventions linked from the first paragraph on our wiki page. We deviate from those in only a couple of small ways, which is why our page seems quite brief."
You make some good suggestions, so here is what I have done:
* Update the "Coding Standards" page with clarifications and other information from our internal conversations that were prompted by your post.
* Lock that page from external edits, since the content should be determined by the engineering team.
* Rename "3.0 JavaScript Code Standards" to "JavaScript Code Standards"
* Create a separate page for conversations around community coding standards. It is called "Community Coding Standards".
* Rather than defining standards in detail, perhaps it would be quicker and more useful to build a list of "best practice" examples of each relevant file type and packaging style. I'll start a place for a list on the wiki page.
I encourage everyone on this list to update the Community Coding Standards page with your suggestions and tips. That goes for all the wiki pages. The official documentation is produced by the engineering team, but anyone can edit the wiki and we hope that you do.
Thank you for raising the issue Peter. I look forward to continuing the discussion at DevCon.
Richard
Reply all
Reply to author
Forward
0 new messages