Rules

Secret ingredients to quality software

Rules to Better Naming Conventions - 21 Rules

  1. Do you follow naming conventions?

    It's the most obvious - but naming conventions are so crucial to simpler code, it's crazy that people are so loose with them...

    For Javascript / Typescript 

    Google publishes a JavaScript style guide. For more guides, please refer to this link: Google JavaScript Style Guide

    Here are some key points:

    • Use const or let – Not var
    • Use semicolons
    • Use arrow functions
    • Use template strings
    • Use uppercase constants
    • Use single quotes

    See 13 Noteworthy Points from Google’s JavaScript Style Guide

    For C# Java

    See chapter 2: Meaningful Names Clean Code: A Handbook of Agile Software Craftsmanship

    For SQL (see Rules to Better SQL Databases)

  2. Boolean Properties must be prefixed by a verb. Verbs like "Supports", "Allow", "Accept", "Use" should be valid. Also properties like "Visible", "Available" should be accepted (maybe not). Here is how we name Boolean columns in SQL databases.

    public bool Enable { get; set; }
    public bool Invoice { get; set; }

    Bad Example

    public bool Enabled { get; set; }
    public bool IsInvoiceSent { get; set; }

    Good Example - Naming Convention for Boolean Property

    We have a program called SSW Code Auditor to check for this rule.

  3. When creating WebAPIs for your applications, it is useful to keep the naming consistent all the way from the back-end to the front-end.

    Table name: Employees Endpoint: /api/Users

    Bad Example: The endpoint is different to the table name

    Table name: Employees Endpoint: /api/Employees

    Good Example: Table name is the same as the WebAPI endpoint

    By making the endpoint name the same as the table name, you can simplify development and maintenance of the WebAPI layer.

    In some circumstances you may not have direct control over the database, and sometimes you may be exposing a resource that doesn't have a meaningful analogue in the database. In these situations, it may make sense to have different endpoint names - if doing so will simplify development for consumers of your WebAPI endpoints.

  4. Test Projects

    Tests typically live in separate projects – and you usually create a project from a template for your chosen test framework.Because your test projects are startup projects (in that they can be independently started), they should target specific .NET runtimes and not just .NET Standard.A unit test project usually targets a single code project.

    Project Naming

    Integration and unit tests should be kept separate and should be named to clearly distinguish the two.This is to make it easier to run only unit tests on your build server (and this should be possible as unit tests should have no external dependencies)Integration tests require dependencies and often won't run as part of your build process. These should be automated later in the DevOps pipeline.

    Test Project Location

    Test projects can be located either:

    • Directly next to the project under test – which makes them easy to find, or
    • In a separate tests location – which makes it easier to deploy the application without tests included.

    clean architecture naming
    Figure: In the above project, the tests are clearly placed in a separate location which makes it easy to deploy to production without them. It’s easy to tell which project is under test and what style of tests will be found in each test project. https://github.com/jasontaylordev/CleanArchitecture

    Naming Conventions for Tests

    There are a few “schools of thought” when it comes to naming the tests themselves.Internal consistency within a project is important.It’s usually a bad idea to name tests after the class or method under test – as this naming can quickly get out-of-sync if you use refactoring tools – and one of the key benefits from unit testing is the confidence to refactor!

    Remember that descriptive names are useful – but the choice of name is not the developer’s only opportunity to create readable tests.

    • Write tests that are easy to read by following the three A's (Arrange, Act, and Assert)
    • Use a good assertion library to make test failures informative (e.g. Shouldly or FluentAssertions)
    • Use comments and refer to bug reports to document the “why” when you have a test for a specific edge-case.
    • Remember that the F12 shortcut will navigate from the body of your test straight to the method you’re calling.
    • The point of a naming convention is to make code more readable, not less - so use your judgement and call in others to verify your readability.

    bad naming
    Figure: Bad Example - From the test explorer view you cannot tell what a test is meant to test from the name

    [Method/PropertyName]_Should_[ExpectedBehavior]_When_[StateUnderTest]

    Figure: The "should" naming convention is effective – it encourages developers to clearly define the expected result upfront without requiring too much verbosity. The following test names use the "should" naming convention:

    Withdraw_Should_ThrowException_When_InvalidAccountInfo Checkout_Should_Add10Precent_When_CountryIsAustralia Purchase_Should_Suceed_When_BalanceIsWithinCreditLimit

    Figure: Good Examples - Without looking at code, I know what the unit tests are trying to do

    A list of other suggested conventions can be found here: 7 Popular Unit Test Naming Conventions.

  5. Do you name your Azure resources correctly?

    Organizing your cloud assets starts with good names. It is best to use all lower case and use “-“ and not put the Resource Type in the name. Different resource types can be identified by the resource icon.

    Azure defines naming rules and restrictions for Azure resources.

    bad azure naming
    Bad Example: This is using a mixture of upper case and lower case letters, plus specifying the resource type

    good azure naming
    Good Example: Use lowercase letters and ”-”

  6. To help maintain order and control in your Azure environment, applying tags to resources and resources groups is the way to go.

    Azure has the Tag feature, which allows you to apply different Tag Names and values to Resources and Resource Groups:

    tags in resources group
    Figure: Little example of Tags in Resource Groups

    You can leverage this feature to organize your resources in a logical way, not relying in the names only. E.g.

    • Owner tag: You can specify who owns that resource
    • Environment tag: You can specify which environment that resource is in

    Tip: Do not forget to have a strong naming convention document stating how those tags and resources should be named. You can use this Microsoft guide as a starter point: Recommended naming and tagging conventions.

  7. Do you use Azure Policies?

    If you use a strong naming convention and is using Tags to its full extent in Azure, then it is time for the next step.

    Azure Policies is a strong tool to help in governing your Azure subscription. With it, you make it easier to fall in The Pit of Success when creating or updating new resources. Some features of it:

    1. You can deny creation of a Resource Group that does not comply with the naming standards
    2. You can deny creation of a Resource if it doesn't possess the mandatory tags
    3. You can append tags to newly created Resource Groups
    4. You can audit the usage of specific VMs or SKUs in your Azure environment
    5. You can allow only a set of SKUs within Azure

    Azure Policy allow for making of initiatives (group full of policies) that try to achieve an objective e.g. a initiative to audit all tags within a subscription, to allow creation of only some types of VMs, etc...

    You can delve deep on it here: https://docs.microsoft.com/en-us/azure/governance/policy/overview

    compliant initiative azure policy
    Figure: Good Example - A fully compliant initiative in Azure Policy"

  8. Do you know how to name a GitHub Repository?

    Consistent naming is important so that users of your GitHub account can easily find what they are looking for and so that you appear professional.

    name github bad
    Figure: Bad example – Repository names are not consistently formatted

    name github ok
    Figure: OK example – Repositories are following the lower-cased hyphenated format that is common for open source projects

    name github good
    Figure: Good example – Repository names are name-spaced in the format [CompanyName].[ProjectName]

  9. Do you know how to name your builds?

    You should always follow a naming standard when naming your builds. This helps you identify their purpose at a glance.

    The build name should have the following suffixes, depending on their purpose:

    • .CI - For continuous integration builds. These are triggered automatically and do not deploy anywhere.
    • .CD.[Environment] - For continuous delivery builds. These are triggered automatically and deploy to an environment. You should specify which environment it deploys to as well.

    buildnames

    Good Example: We have two continuous delivery builds to our staging environment.

  10. Generally, every client should have a dev and a test database, so the dev database needs to have the postfix "Dev" and the test database need to have the postfix "Test"(E.g. SSWCRMDev, SSWCRMTest). However, you don't need any postfix for the production database.

    Figure: Bad Example - Database with bad names

    Figure: Good Example - Database with standard names

  11. This standard outlines the standard on naming objects within SQL Server. Use these standards when naming any object or if you find an older object that doesn't follow these standards within SSW.

    All feedback is welcome. Thanks to all who gave feedback. A special thanks to Andy Baron.

    ObjectPrefixExample
    TableClients
    Column (PK)Id
    Column (FK)ClientId
    Temporary Table_zt_ztClients
    System Table_zs_zsDataVersion, _zsVersionLatest
    Viewvw, gy_vwClientsWithNoPhoneW, gy_ClientsWithNoPhoneW
    Stored Procedureproc, gp_procSelectClientsClientID, gp_SelectClientsClientID
    TriggertrgtrgOrderIU
    Default*dft *dftToday *
    RulerulrulCheckZIP
    User-Defined DatatypeudtudtPhone
    User-Defined FunctionsudfudfDueDates

    * We never use defaults as objects, this is really an old thing that is just there for backwards compatibility. Much better to use a default constraint.

    Other Links

    SQL Server Coding Standards - Part 1 By Steve Jones on SQL Server Central

  12. This standard outlines the procedure on naming Relationships at SSW for SQL Server. Use this standard when creating new Relationships or if you find an older Relationship that doesn't follow that standard.

    Do you agree with them all? Are we missing some? Let us know what you think.

    Syntax

    Relationship names are to have this syntax:

    [PrimaryTable] - [ForeignTable]
    [ 1 ] - [ 2 ]

    [1] The table whose columns are referenced by other tables in a one-to-one or one-to-many relationship.Rather than accepting the default value i.e. ClientAccount_FK01 that is given from upsizing.

    Figure: Bad Example - using the default relationship name

    We recommend using Prod-ClientAccount.

    Figure: Good Example - using a more descriptive relationship name

    The good thing is when you look at the relationship from the other side it is there as well.

    Figure: Relationship name shown on the other table

    We also believe in using Cascade Updates - but never cascade deletes.

  13. This standard outlines the standard on naming Stored Procedures within SQL Server. Use these standards when creating new Stored Procedures or if you find an older Stored Procedure that doesn't follow these standards within SSW.

    Note: Stored Procedures will run fractionally slower if they start with a prefix of sp_   This is because SQL Server will look for a system stored proc first. Therefore we never recommend starting stored procs with a prefix of sp_ Do you agree with them all? Are we missing some? Let us know what you think.

    Syntax

    Stored Procedure names are to have this syntax:[proc] [MainTableName] By [FieldName(optional)] [Action][  1  ] [         2          ]     [       3                  ] [   4    ][1] All stored procedures must have the prefix of 'proc'. All internal SQL Server stored procedures are prefixed with "sp_", and it is recommended not to prefix stored procedures with this as it is a little slower.[2] The name of the table that the Stored Procedure accesses.[3] (optional) The name of the field that are in the WHERE clause. ie. procClientByCoNameSelect, procClientByClientIDSelect[4] Lastly the action which this Stored Procedure performs.

    If Stored Procedure returns a recordset then suffix is 'Select'.If Stored Procedure inserts data then suffix is 'Insert'.If Stored Procedure updates data then suffix is 'Update'.If Stored Procedure Inserts and updates then suffix is 'Save'.If Stored Procedure deletes data then suffix is 'Delete'.If Stored Procedure refreshes data (ie. drop and create) a table then suffix is 'Create'.If Stored Procedure returns an output parameter and nothing else then make the suffix is 'Output'.

    ALTER PROCEDURE procClientRateOutput
    
             @pstrClientID VARCHAR(6) = 'CABLE',
             @pstrCategoryID VARCHAR(6) = '<All>',
             @pstrEmpID VARCHAR(6)='AC',
             @pdteDate datetime = '1996/1/1',
             @curRate MONEY OUTPUT
    
    AS
    
    -- Description: Get the $Rate for this client and this employee
    --         and this category from Table ClientRate
    
    SET @curRate = (
                    SELECT TOP 1 Rate
                    FROM ClientRate
                    WHERE ClientID=@pstrClientID
                    AND EmpID=@pstrEmpID
                    AND CategoryID=@pstrCategoryID
                    AND DateEnd > @pdteDate
                    ORDER BY DateEnd
                   )
    
    IF @curRate IS NULL
    
             SET @curRate =
    (
                    SELECT TOP 1 Rate
                    FROM ClientRate
                    WHERE ClientID=@pstrClientID
                    AND EmpID=@pstrEmpID
                    AND CategoryID='<ALL>'
                    AND DateEnd > @pdteDate
                    ORDER BY DateEnd
                   )
    
    RETURN

    Figure: Good Example - stored proc that returns only an output parameter

    Select 'procGetRate' or 'sp_GetRate' Insert 'procEmailMergeAdd'

    Figure: Bad Example

    'procClientRateSelect' 'procEmailMergeInsert'

    Figure: Good Example

  14. Keeping track of CRM customization changes is just as difficult as back-end database changes. We have a rule Is a Back-end structural change going to be a hassle? which provide you an example how you should keep track of back-end changes. You can apply this rule to CRM changes and use a naming convention on each customization backup file to identify and keep track of your changes.

    Your customization file name should be:

    [IncrementalNumber]_[Entity]_[Date].zip, for example: 001_account_29042009.zip

    The file's name can tell you which entity you made changes and which date the changes were made. The incremental number will provides us step by step instruction on how to produce the current CRM system from a vanilla Microsoft Dynamics CRM.

    CRM2011 has significant improvements in this area with Solutions. In CRM 2011 we use versioned solutions along with source control.

  15. Do you know how to name documents?

    When naming documents, use kebab-case to separate words to make your files more easily discoverable.

    Avoid spaces

    Monthly Report.docx

    Bad example: File name uses a space to separate words

    As far as search goes, using spaces is actually a usable option. What makes spaces less-preferable is the fact that the URL to this document will have those spaces escaped with the sequence %20. E.g. sharepoint/site/library/Monthly%20Report.docx. URLs with escaped spaces are longer and less human-readable.

    Know more on Do you remove spaces from your folders and filename?

    Avoid CamelCase

    MonthlyReport.docx

    Bad example: CamelCase - File name doesn't have spaces but also doesn't contain any separators between words

    This is a popular way to combine words as a convention in variable declarations in many coding languages, but shouldn't be used in document names as it is harder to read. Also, a file name without spaces means that the search engine doesn't know where one word ends and the other one begins. This means that searching for 'monthly' or 'report' might not find this document.

    Avoid Snake_Case

    Monthly_Report.docx

    Figure: OK example - underscored (Snake_Case) URLs have good readability but are not recommended by Google

    Underscores are not valid word separators for search in SharePoint, and not recommended by others. Also, sometimes underscores are less visible to users, for example, when a hyperlink is underlined. When reading a hyperlink that is underlined, it is often possible for the user to be mistaken by thinking that the URL contains spaces instead of underscores. For these reasons it is best to avoid their use in file names and titles.

    Use kebab-case

    monthly-report.docx

    Good Example: kebab-case - File name uses dashes to separate words

    A hyphen (or dash) is the best choice, because it is understood both by humans and all versions of SharePoint search.

    You may use Uppercase in the first letter in Kebab-Case, however it's important to keep consistency

    Extra

    • Add relevant metadata where possible

    If a document library is configured with metadata fields, add as much relevant information as you can. Metadata is more highly regarded by search than the contents within documents, so by adding relevant terms to a documents metadata, you will almost certainly have a positive effect on the relevance of search results.

    • Use descriptive file names and titles

    The file name and title is regarded more highly by search than the content within documents. Also, the title or file name is what is displayed in the search results, so by making it descriptive, you are making it easier for people who perform searches to identify the purpose of your document.

  16. Client Teams should be prefixed with “Client –“ so it is easier to identify them.

    client naming bad
    Bad Example: Client team without the "Client –" prefix

    client naming good
    Good Example: Well prefixed Teams make Client-related teams easier to identify

  17. Do you standardize AD group names?

    The use of standardized AD Group names is a simple yet crucial step towards building more manageable software. Raining in on the number of AD Groups used by an application will make it simpler to manage and allow new developers to pick up an existing project faster.

    You can save yourself countless confused conversations by standardizing AD Group Names.

    For example, this is a list of AD groups associated with products:

    SSWSugarLearningEvents
    SSWCodeAuditorAlerts
    SSWLinkAuditorDevs

    Figure: Bad Example – It is difficult to know the correct name for an AD group

    SSWSugarLearning
    SSWSugarLearningEvents
    SSWCodeAuditor
    SSWCodeAuditorEvents
    SSWLinkAuditor
    SSWLinkAuditorEvents

    Figure: Good Example – By standardizing the names of AD groups it saves confusion

    Note: For large organizations, a better way is to use a type of group (eg. Local or Global)... then the entity it is associated to… then the resource (or service).

    Example #1:

    L-LocalGroupName-
       SYD-EntityName-
       SP-Sharepoint-

    That becomes “L-SYD-SP-SSW-Users"

    Example #2:

    G-GlobalGroupName-
       SYD-EntityName-
       SP-Sharepoint-

    That becomes “G-SYD-SP-SSW-Users"

    Note: You would not use this naming convention for distribution groups – as they would display to users.

    It is recommended by default to have two AD groups per product. The following table should be used as a guide for naming them:

    NameTypePurpose
    SSW<ProductName>Distribution groupThis email is used to send emails to the development team for a product.
    SSW <ProductName>EventsMailboxActs as the collection point for all automatic notifications. For example notifications from Elmah and/or application insights.
  18. When we configure networks we give all computers in the company a naming theme like:

    • Buildings
    • Cars
    • Countries
    • Colours
    • Fruits
    • Vegetables, etc

    At SSW we have adopted the animal kingdom.

    SSW computer Great Pyrenees
    Figure: We name the PCs and label them - this one is "Great Pyrenees"

    While you are attaching the label, it is also a good idea to affix a business card to the underside of the computer. This way if you lose your machine, anyone who finds it can easily contact you.

  19. When you configure Hyper-V Clustering, each node will have upwards of 4 network adapters, some virtual and some physical. It is important to give these adapters meaningful names so you know what network adapter does what.

    naming bad
    Figure: Bad Example - It makes it hard to know what network adapter does what if you don't have meaningful names

    naming good
    Figure: Good example - As an example naming convention for network adapters on each node

    naming good2
    Figure: Good Example - It is easy to tell which network adapter does what when they have meaningful names

  20. When your Hyper-V environment is spread across multiple hosts and contains many Virtual Servers, it can get very confusing to find the one you are looking for amongst them all. This is why you should use a standard naming convention for all your Virtual machines.

    naming badexample
    Bad Example - How do you know what machine is what?

    The standard we use for Production Virtual Machine naming is as follows: NetBIOSName-ServiceName.
    For example: Falcon-SCVMM.

    The standard we use for Development Virtual Machine naming is as follows: DEV-NetBIOSName-ServiceName-DeveloperInitials.
    For example: DEV-demo2010a-SP2010MSInfoWorker-JL.

    naming goodexample
    Good Example - It is easy to tell which VM is which when they are named to a standard

  21. When you look at the Service Calendar, you want to be able to see, at a glance, who is working on what.

    To do this, the subject field of appointments should be as follows:

    Client [Project] - Name[s]

    The project name (in parentheses) is optional and only used if there is more than one project happening simultaneously.

    You can have 1 or many names, depending on the booking.

    Go to ACME Corp Work onsite for ACME Corp Mehmet working at ACME Corp

    Figure: Bad example - all inconsistent and hard to read

    ACME Corp - Mehmet ACME Corp - Mehmet, Dan ACME Corp (SharePoint) - Dan

    Figure: Good Examples

    The same format should also be used for leave requests (the same for normal calendar appointments/invitations).

    Leave - Mehmet

    Figure: Good Example

    Related rules

    • Do you realize the importance of a good email Subject?
    • Appointments - Do you make sure your appointment has a good subject?
We open source. Powered by GitHub