views:

332

answers:

5

In a not-so-small program, when you have not-so-few entities, in order to maintain code readability, common terms, and otherwise improve mutual understanding between team members, one have to define and maintain program vocabulary.

How do you (or your company) deal with this task, what discipline do you have, what arrangements do you introduce?

+3  A: 

Most projects of reasonable size should have a programming/coding standards document that dictates common conventions and naming guidelines that should be followed.

Another way to help with this is through code reviews. Obviously some coordination among reviewers is required (the document helps with that, too). Code reviews help keep the greener devs and senior devs alike on track and act as an avenue to enforce the coding standards.

Michael Haren
The question was "HOw" not "WHAT"
Ilya Ryzhenkov
Perhaps clarify in the question, then?You asked how, and Michael said with a standards document.
William Keller
William, so you think just having a "standard" document will make program vocabulary maintainable?
Ilya Ryzhenkov
At my company, the conventions document is often customized for each project to incorporate whatever style and DSL the customer brings to the table.
Michael Haren
I just added the code review approach.
Michael Haren
Michael, creating the document is one thing. How do you maintain the document, and (more interesting), how do you make your team to follow the document?
Ilya Ryzhenkov
The conventions document is maintained throughout the life of a project--it's a living document.
Michael Haren
I don't quite get the answer. You say "document is maintained", but how is it maintained? What discipline, practice, dictatorship do you have in place to make it work?
Ilya Ryzhenkov
For example, if, during a code review you came across something that wasn't well defined in the document, you'd either update the doc at that time or tell the developer to do it and approve the change.
Michael Haren
Michael, do I get it right, that the discipline is code review? I.e. code review ensures common vocabulary among team members, and document is needed for new members to start with?
Ilya Ryzhenkov
Yes. I guess I hadn't really given it so much thought before. Code reviews are the mechanism by which you maintain your standards and enforce them.
Michael Haren
A: 

Divide your packages/modules into logical groups and use descriptive and concise names. Avoid generic names except if they are really counters etc. Create conventions for groups of functions or functionality and stick to them.

Florian Bösch
After I create conventions, how would I maintain them?
Ilya Ryzhenkov
I'd say discipline
Florian Bösch
A: 

Domain Driven Design is interesting here, since it encourages programmers to embrace the domain vocabulary. On top of that, there is some design conventions, which allow you to refer parts of your application using well known terms, like services, repositories, factories, etc.

Combining domain vocabulary and using technical conventions above it could be a good solution.

Romain Verdier
A: 

My team keeps this kind of information (conventions/vocabulary etc.) on a wiki. This makes it easy to keep up to date and share.

Chris
I wonder how do you keep it up to date? Do you have any rules about "when you change IFooElement to IFooEntity, please update wiki on the pages a,b, and c?"
Ilya Ryzhenkov
This can be problematic if people are lazy. The useful pages are kept up to date as people use the frequently and if you find a problem/mistake then you have to fix it. The less useful pages should be deleted or consolidated into something useful that can be maintained more easily.
Chris
+1  A: 

@Ilya Ryzhenkov,

I'm afraid most companies don't have such practice :) I've worked in the not-so-small company with multimillion LOC code base and they don't have any documentation at all (beside common coding guideline)

On one of my projects we maintained thesaurus of common terms used in our application domain and used it during code review. I analyzed .NET XML documentation diff from time to time to decide which entities\terms should be added to the thesaurus. Only means to enforce compliance with thesaurus was coding guideline.

Wiki approach proved to be non-applicable because nobody cares to update it regularly :)

I'm wondering what methods do you use at JetBrains ? I've inspected ReSharper's code in Reflector and was amazed with number and names of entities :)

aku