What is everyones best practices for naming conventions for doc types, templates, macros and fields?
I'm interested in ones that are helpful as well as good practice. I started not really using one but got in a bit of a mess once I'd added a few different docs, etc. So started refactoring and coming up with something better. Heres where I am right now:
Namespacing - I've started adding namespaces on to the front of all my variables, it just makes it easier to see what stuff is/where it lives/where to find it at a glance rather than guessing or digging around. So for example I'll add the doc type name to the front of all my doc type fields (Homepage.heading, AboutUs.address, etc).
Friendly names - I use a nice descriptive name that leaves the user in little doubt. I use a Base Doc Type alot but its never meant to be implemented directly so the name says so "Base Doc Type (do not use directly)" :)
Doc Types - These use CamelCase with a leading uppercase letter (Homepage, Basepage, AboutUs)
Properties/Alias - These use camelCase with a leading lowercase letter (pageTitle, metaKeywords, etc.)
Macros - These start with the type of macro they are (eg XSL.MacroName, NET.MacroName, etc.)
This does make the XSL a little longer but when reading through the XML or adding items to templates via the wizards its easy to see straight away what is what.
In my XSL templates I also tend to namespace all my template names, this from my experience using XSL for other projects that use included XSL files, it all too quickly gets confusing as to where templates live. By namespacing them its obvious (Hotel.renderPrice, Homepage.renderNews, Blog.comments, etc.) I do this even if the file does not include any other XSL files as it might one day or it might get included into another file itself.
I also namespace my variables too( $GLOBAL.dayOfTheWeek, $Homepage.isChristmas, etc.)
What naming convention are you using? How can I improve the above so far, I know its not 100% but it would be nice to have a sample doc for other Umbraco users for a good standard to follow.
Thinking ahead if packages where written with one standard then we could know that they would play nice and others would be able to pick them up quicker?
I have found it useful to also add the type of object to the name. I find it helpful to know which type of object I'm currently dealing with just by looking at the name, especially when working with doctypes and templates. Some examples:
FirstpageTemplate PressreleaseDoctype
I don't use it consistently tough since I don't give the objects in the media archive names like FolderMedia or FileMedia. Of course one could do that as well.
When filtering nodes based on its doctype in an XSLT-script I find it easier to sift through the code and easily identify the places where the doctypes are mentioned if I have the word "Doctype" in its name. So when working with media objects in the same fashion I think it would be useful to give them names that reflect their object type.
With each website I develop with Umbraco, my naming convention seems to evolve - which has become a pain when I go back to work on earlier projects; I always want to rename everything! (but I hold-back).
For most items, such as macros and templates, I use PascalCase (i.e. upper camel case) - keeping the as descriptive as possible.
Personally I wouldn't prefix the macros with XSLT/NET - because does it matter what the underlying control is? Then what if you decide that you want to switch from XSLT to .NET, would you rename the macro? (and update all references to it?)
My main focus for naming conventions has been document-types. I have a base doc-type, called "Base", which contains the hidden Umbraco-specific properties (umbracoRedirect, umbracoUrlName, umbracoUrlAlias, umbracoInternalRedirectId, umbracoNaviHide) - under a tab called "Meta". Then all other doc-types inherit those - which has proved extremely useful in later stages of the various projects.
Following suit from those, I use camelCase (lower camel case) for all my properties... so "pageTitle", "pageSubtitle" ... but then I went against the grain and started using "bodyText" for the main content. (I think it's because I saw that being used in Doug's XSLTSearch?! (I could be wrong though).
Overall I try to keep the names as descriptive and short as possible - using a mix of upper/lower camel case. The only exception is what I call the "physical" files (XSLT, JavaScript, CSS, ASCX) - I tend to follow UK government guidelines of lowercase/hyphenated filenames:
i.e. "html-sitemap.xslt" or "sidebar-navigation.xslt", etc.
Currently I tend to go with lowerCamelCase for all alias' as this seems to be the convention used by Umbraco themselves. I'm not to sure on the namespacing, as I can see this being a pane if you want to reuse something later on a different doc type, then you'd have to replace em all.
In terms of friendly names, I tend to have some standard suffix' such as Index and Page (ie News Index, News Page) which all "visual" pages must have. Then any non visual (information only) doc types are generaly just named after the entity (ie Testimonial).
With my macros I still follow the lowerCamelCase naming (I also don't agree with the XSL / NET prefix, seems too restrictive). The only other convention I have here is with the physical file names of my XSL files. I tend to prefix these with either Macro. or Include. this way I can keep all my macros and includes grouped together in the tree.
I'll have to give the namespacing of XSL templates and variables a go as I can see your reasonings for this.
Ok, I can see why the macro prefix is bad idea, I was just after a quick pointer as to where to look for the template for each macro but you guys are right its restrictive, ok will drop that one.
I'm thinking of putting a page together in the wiki to list these (no idea how, another thing to learn).
Like the Index/Page idea and the Template/DocType suffix idea too, will adopt those.
Lee know what you mean about changing your mind every project, part of the reason for this thread in the first place, pool our experiences and come up with a rule of thumb standard :)
I believe you should not name doctypes with a “plural” name.
Because future versions of umbraco (Linq to Umbraco) may create ‘auto-plural’ objects which represent a collection of the singular object.
Bad:
Collections
Settings
Components
Setting
Good:
Collection
Setting Collection
Component
Setting
eg: a collection of 'Setting' will be accessed via Settings.All() which would conflict with the 'settings' in 'collections' if you've done it the 'bad' way.
This might be an interesting topic for discussing at CodeGarden during the open session the second day of the conference? Might be a good way to formalize the best practices and finish out the wiki.
Would it be worth it and are there any takers on a moderator of this discussion?
I just took a stab at adding what I'm using at the minute to the wiki (see link above). Seems to work for me. Take a look and edit to your hearts content, hope it helps someone.
I usually also use the approach of prefixing macros with either XSLT or .NET but after reading Lee's arguments I'm rethinking if it's the right way to do it, since he has got a point there.
For the property names I used to use camelcasing with pageTitle, pageText etc. - But recently I have changed my mind. I think that property names should be more generic so it's easier to reuse them writing less code.
I agree that this could be an interesting topic at CG10 :-)
Best Practises - Naming conventions
What is everyones best practices for naming conventions for doc types, templates, macros and fields?
I'm interested in ones that are helpful as well as good practice. I started not really using one but got in a bit of a mess once I'd added a few different docs, etc. So started refactoring and coming up with something better. Heres where I am right now:
Namespacing - I've started adding namespaces on to the front of all my variables, it just makes it easier to see what stuff is/where it lives/where to find it at a glance rather than guessing or digging around. So for example I'll add the doc type name to the front of all my doc type fields (Homepage.heading, AboutUs.address, etc).
Friendly names - I use a nice descriptive name that leaves the user in little doubt. I use a Base Doc Type alot but its never meant to be implemented directly so the name says so "Base Doc Type (do not use directly)" :)
Doc Types - These use CamelCase with a leading uppercase letter (Homepage, Basepage, AboutUs)
Properties/Alias - These use camelCase with a leading lowercase letter (pageTitle, metaKeywords, etc.)
Macros - These start with the type of macro they are (eg XSL.MacroName, NET.MacroName, etc.)
This does make the XSL a little longer but when reading through the XML or adding items to templates via the wizards its easy to see straight away what is what.
In my XSL templates I also tend to namespace all my template names, this from my experience using XSL for other projects that use included XSL files, it all too quickly gets confusing as to where templates live. By namespacing them its obvious (Hotel.renderPrice, Homepage.renderNews, Blog.comments, etc.) I do this even if the file does not include any other XSL files as it might one day or it might get included into another file itself.
I also namespace my variables too( $GLOBAL.dayOfTheWeek, $Homepage.isChristmas, etc.)
What naming convention are you using? How can I improve the above so far, I know its not 100% but it would be nice to have a sample doc for other Umbraco users for a good standard to follow.
Thinking ahead if packages where written with one standard then we could know that they would play nice and others would be able to pick them up quicker?
Hi Peter!
I have found it useful to also add the type of object to the name. I find it helpful to know which type of object I'm currently dealing with just by looking at the name, especially when working with doctypes and templates. Some examples:
FirstpageTemplate
PressreleaseDoctype
I don't use it consistently tough since I don't give the objects in the media archive names like FolderMedia or FileMedia. Of course one could do that as well.
When filtering nodes based on its doctype in an XSLT-script I find it easier to sift through the code and easily identify the places where the doctypes are mentioned if I have the word "Doctype" in its name. So when working with media objects in the same fashion I think it would be useful to give them names that reflect their object type.
Regards,
Thomas Kahn
Good topic Peter!
With each website I develop with Umbraco, my naming convention seems to evolve - which has become a pain when I go back to work on earlier projects; I always want to rename everything! (but I hold-back).
For most items, such as macros and templates, I use PascalCase (i.e. upper camel case) - keeping the as descriptive as possible.
Personally I wouldn't prefix the macros with XSLT/NET - because does it matter what the underlying control is? Then what if you decide that you want to switch from XSLT to .NET, would you rename the macro? (and update all references to it?)
My main focus for naming conventions has been document-types. I have a base doc-type, called "Base", which contains the hidden Umbraco-specific properties (umbracoRedirect, umbracoUrlName, umbracoUrlAlias, umbracoInternalRedirectId, umbracoNaviHide) - under a tab called "Meta". Then all other doc-types inherit those - which has proved extremely useful in later stages of the various projects.
Following suit from those, I use camelCase (lower camel case) for all my properties... so "pageTitle", "pageSubtitle" ... but then I went against the grain and started using "bodyText" for the main content. (I think it's because I saw that being used in Doug's XSLTSearch?! (I could be wrong though).
Overall I try to keep the names as descriptive and short as possible - using a mix of upper/lower camel case. The only exception is what I call the "physical" files (XSLT, JavaScript, CSS, ASCX) - I tend to follow UK government guidelines of lowercase/hyphenated filenames:
i.e. "html-sitemap.xslt" or "sidebar-navigation.xslt", etc.
Cheers, Lee.
Hey Pete,
Currently I tend to go with lowerCamelCase for all alias' as this seems to be the convention used by Umbraco themselves. I'm not to sure on the namespacing, as I can see this being a pane if you want to reuse something later on a different doc type, then you'd have to replace em all.
In terms of friendly names, I tend to have some standard suffix' such as Index and Page (ie News Index, News Page) which all "visual" pages must have. Then any non visual (information only) doc types are generaly just named after the entity (ie Testimonial).
With my macros I still follow the lowerCamelCase naming (I also don't agree with the XSL / NET prefix, seems too restrictive). The only other convention I have here is with the physical file names of my XSL files. I tend to prefix these with either Macro. or Include. this way I can keep all my macros and includes grouped together in the tree.
I'll have to give the namespacing of XSL templates and variables a go as I can see your reasonings for this.
Cheers
/Matt
Ok, I can see why the macro prefix is bad idea, I was just after a quick pointer as to where to look for the template for each macro but you guys are right its restrictive, ok will drop that one.
I'm thinking of putting a page together in the wiki to list these (no idea how, another thing to learn).
Like the Index/Page idea and the Template/DocType suffix idea too, will adopt those.
Lee know what you mean about changing your mind every project, part of the reason for this thread in the first place, pool our experiences and come up with a rule of thumb standard :)
I believe you should not name doctypes with a “plural” name.
Because future versions of umbraco (Linq to Umbraco) may create ‘auto-plural’ objects which represent a collection of the singular object.
Bad:
Good:
eg: a collection of 'Setting' will be accessed via Settings.All() which would conflict with the 'settings' in 'collections' if you've done it the 'bad' way.
It'd be nice to see a standard approach to naming conventions on the wiki (perhaps here ?)
This might be an interesting topic for discussing at CodeGarden during the open session the second day of the conference? Might be a good way to formalize the best practices and finish out the wiki.
Would it be worth it and are there any takers on a moderator of this discussion?
-Chris
I just took a stab at adding what I'm using at the minute to the wiki (see link above). Seems to work for me. Take a look and edit to your hearts content, hope it helps someone.
I usually also use the approach of prefixing macros with either XSLT or .NET but after reading Lee's arguments I'm rethinking if it's the right way to do it, since he has got a point there.
For the property names I used to use camelcasing with pageTitle, pageText etc. - But recently I have changed my mind. I think that property names should be more generic so it's easier to reuse them writing less code.
I agree that this could be an interesting topic at CG10 :-)
/Jan
Hi I checked the wiki for naming convention and cannot find any for folder/directory naming.
what is the naming convention for folders/directories? camelCase or PascalCase?
Standard template from visual studio is using PascalCase.
most folders in umbraco use camelCase, but I still see PascalCase used(LiveEditing, Trees, ActionHandlers)
I checked umbraco ver 5 alpha3 and found out that folder naming convention is : PascalCase (different than ver 4.7).
this is sample file listing showing that there are still no standard naming in version 5 :(
\Areas\Umbraco\Content\Images\DocTypeIcons\package.png
\Areas\Umbraco\Content\Images\DocTypeIcons\TreeSprites.css
\Areas\Umbraco\Content\Images\DocTypeIcons\TreeSprites.png
\Areas\Umbraco\Content\Images\DocTypeThumbs\developer.png
\Areas\Umbraco\Content\Images\DocTypeThumbs\folder_media.png
\Areas\Umbraco\Content\Images\DocTypeThumbs\memberGroup.png
\Areas\Umbraco\Content\Images\DocTypeThumbs\xml.png
\Areas\Umbraco\Content\Styles\ericmeyer.reset.css
\Areas\Umbraco\Content\Styles\Error.css
\Areas\Umbraco\Content\Styles\Exception.css
\Areas\Umbraco\Content\Styles\Login.css
\Areas\Umbraco\Modules\CodeMirror\mode\javascript\index.html
\Areas\Umbraco\Modules\CodeMirror\mode\javascript\javascript.css
\Areas\Umbraco\Modules\CodeMirror\mode\javascript\javascript.js
\Areas\Umbraco\Modules\jQueryUI\ui-lightness\images\ui-icons_ffffff_256x240.png
\Areas\Umbraco\Modules\jQueryUI\v4\images
\Areas\Umbraco\Modules\jQueryUI\v4\jquery-ui-umbraco-v4.css
\Areas\Umbraco\Modules\jQueryUI\v4\images\ui-icons_666666_256x240.png
\Areas\Umbraco\Modules\Modal\jqDnR.js
\Areas\Umbraco\Modules\Modal\jqModal.css
\Areas\Umbraco\Modules\Modal\jqModal.js
\Areas\Umbraco\Modules\Modal\Images\modal-gradient.gif
\Areas\Umbraco\Modules\Modal\Images\overlay-background.gif
\Areas\Umbraco\Modules\Notifications\NotificationManager.js
\Areas\Umbraco\Modules\Notifications\Notifications.css
\Areas\Umbraco\Modules\Notifications\images\warning.png
\Areas\Umbraco\Modules\TinyMCE\tiny_mce_popup.js
\Areas\Umbraco\Modules\TinyMCE\plugins\advhr\editor_plugin.js
\Areas\Umbraco\Modules\TinyMCE\plugins\advhr\langs
\Areas\Umbraco\Modules\Tree\ApplicationPersistence.js
\Areas\Umbraco\Modules\Tree\MenuItems.js
\Areas\Umbraco\Modules\Tree\NodeFormatter.js
\Areas\Umbraco\Modules\Tree\themes\umbraco\ContextMenuBg.gif
\Areas\Umbraco\Modules\Tree\themes\umbraco\d.gif
\Areas\Umbraco\Modules\Tree\themes\umbraco\MenuSprites.png
\Areas\Umbraco\Modules\Tree\themes\umbraco\OverlayNewVersion.png
\Areas\Umbraco\Scripts\jQuery\jquery.validate.js
\Areas\Umbraco\Scripts\jQuery\jquery.validate.min.js
\Areas\Umbraco\Scripts\KnockoutJs\knockout-1.2.1.js
\Areas\Umbraco\Scripts\KnockoutJs\knockout.extensions.js
\Areas\Umbraco\Scripts\Microsoft\MicrosoftAjax.debug.js
\Areas\Umbraco\Scripts\Microsoft\MicrosoftAjax.js
\Areas\Umbraco\Scripts\Umbraco.UI\UiElementFactory.js
\Areas\Umbraco\Scripts\Umbraco.UI\UiPanel.js
\Areas\Umbraco\Scripts\WebToolkit\webtoolkit.md5.js
\Areas\Umbraco\Views\Default\Index.cshtml
\Areas\Umbraco\Views\Default\InsufficientPermissions.cshtml
\Areas\Umbraco\Views\Default\Login.cshtml
\Areas\Umbraco\Views\Default\Search.cshtml
\Areas\Umbraco\Views\Default\SearchPartial.cshtml
\Areas\Umbraco\Views\Default\TrayPartial.cshtml
\Areas\Umbraco\Views\DocumentTypeEditor\CreateNew.cshtml
\Areas\Umbraco\Views\DocumentTypeEditor\Edit.cshtml
\Areas\Umbraco\Views\DocumentTypeEditor\EditorTemplates
\Areas\Umbraco\Views\DocumentTypeEditor\GenericPropertiesTabPartial.cshtml
\Areas\Umbraco\Views\Shared\_DocumentTypeEditorLayout.cshtml
\Areas\Umbraco\Views\Shared\_EditorLayout.cshtml
is working on a reply...