Coding Standards
kramer.n...@gmail.com
codinf standard. Rather, there was no coding standard and I suggested
that we have one. The existing code is terrible. There are three
developers including me and a lot of old code. One of the other
developers is pro-standardization. The third developer is the one who
wrote all the unreadable code. The third guy has been relocated, but
still works on the code some. We're going to our best to enforce the
standard on the third guy.
The language that we use is MODL (an atrocious language based on c), so
most existing standards tools won't really apply. We have developed a
stylistic standard, that we like a lot, based loosely on Sun's java
standard (http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html)
.
The programming practices standards are a little harder for us to
implement because MODL isn't exactly object oriented and it isn't
exactly procedural either and there is no encapsulation mechanism.
We are further restricted from implementing any ambitious standards
because there is so much legacy code yet there are new requirements
coming in the door and we don't have the staff to re-implement the
backbone of the system.
So we are trying to strike a balance between good practices and easily
implemented practices. Does any one have any sage words for me in my
quest? Specifically, does anyone have any thoughts one what should be
done about the old non-compliant code that needs to be maintained but
is too large to be entirely rewritten? Also are there any meta-coding
standards? Any process ideas deciding on a coding standard or
questions to ask about the code that will illuminate what needs to be
standardized?
Thanks, guys, for any help.
Phlip
> I hav just joined a new company and have been put in charge of their
> codinf standard. Rather, there was no coding standard and I suggested
> that we have one. The existing code is terrible. There are three
> developers including me and a lot of old code. One of the other
> developers is pro-standardization. The third developer is the one who
> wrote all the unreadable code. The third guy has been relocated, but
> still works on the code some. We're going to our best to enforce the
> standard on the third guy.
Are you talking about an esthetic or technical standard?
I like the technical standard "all code shall have unit tests", but that's
hard to enforce!
> We are further restricted from implementing any ambitious standards
> because there is so much legacy code yet there are new requirements
> coming in the door and we don't have the staff to re-implement the
> backbone of the system.
What is the "best" of the current code? Shouldn't you extra an esthetic and
technical standard from what currently works?
> So we are trying to strike a balance between good practices and easily
> implemented practices. Does any one have any sage words for me in my
> quest? Specifically, does anyone have any thoughts one what should be
> done about the old non-compliant code that needs to be maintained but
> is too large to be entirely rewritten? Also are there any meta-coding
> standards? Any process ideas deciding on a coding standard or
> questions to ask about the code that will illuminate what needs to be
> standardized?
If the language is like C, and has a preprocessor, then a test rig like
CUnit should be easy to write.
I'm aware that's not what you asked, but your question resembles "I have a
live chicken; what's a good recipe for chicken soup?" I'm telling you how
to kill and pluck the chicken, first...
--
Phlip
http://www.greencheese.us/ZeekLand <-- NOT a blog!!!
kramer.n...@gmail.com
Well what we have developed is more aesthetic than technical, but I
guess we should have a more technical standard also. The problem is
that there is not a preprocessor/compiler/linker. MODL is the
programming language for the modeling system Extend. The code can only
be compiled and run by Extend unless we were to somehow reverse
engineer that system and write our own version or pick through the dlls
for hooks into the internal compiler, etc. We have neither the time
nor the inclination to do those things. Thus, unit testing while a
great idea would be very difficult. We pretty much have to use our
killer-plucker-butcher-boiler machine to make the chicken soup, but it
would still be nice to use the right ingredients.
Phlip
> Well what we have developed is more aesthetic than technical, but I
> guess we should have a more technical standard also. The problem is
> that there is not a preprocessor/compiler/linker. MODL is the
> programming language for the modeling system Extend.
Then I would use TDD to write a parser and toy compiler. No lie; I have done
it before for simple languages.
You can 'lint' the language by parsing it into a structure in memory, then
sweeping the structure with visitors; the Interpreter Design Pattern.
--
Phlip
http://c2.com/cgi/wiki?ZeekLand <-- NOT a blog!!!
Phlip
>> Well what we have developed is more aesthetic than technical, but I
>> guess we should have a more technical standard also. The problem is
>> that there is not a preprocessor/compiler/linker. MODL is the
>> programming language for the modeling system Extend.
>
> Then I would use TDD to write a parser and toy compiler. No lie; I have
> done it before for simple languages.
http://www.c2.com/cgi/wiki?MsWindowsResourceLint
> You can 'lint' the language by parsing it into a structure in memory, then
> sweeping the structure with visitors; the Interpreter Design Pattern.
All of this will work like a unit test rig; one simply builds a lint system,
runs it before each commit (please don't describe your version control
system), and fixes code that breaks the lint.
Marco
since I was curious, I found this doc that shows some of the MODL
language:
http://www.tbm.tudelft.nl/webstaf/tamratt/Extend_evaluation.pdf
It appears to be procedural. I'm not sure why it is so bad as you
mention.
But in general, proprietary languages (especially those tied to another
program) are usually not desirable because you can't find tools, such
as unit testers, for them.
I would locate some good C coding standard documents and use them as a
basis to get started for your standard. I would also suggest you
locate a copy of the first edition of "Code Complete" which has a bunch
of guidelines for procedural languages (the new edition is mostly OO).
This is an excellent book.
I feel that both technical aspects and style (naming, etc) are
important and should be captured.
Maybe Extend has the capability to create subsystem tests if you design
your code correctly.
H. S. Lahman
> I hav just joined a new company and have been put in charge of their
> codinf standard. Rather, there was no coding standard and I suggested
> that we have one. The existing code is terrible. There are three
> developers including me and a lot of old code. One of the other
> developers is pro-standardization. The third developer is the one who
> wrote all the unreadable code. The third guy has been relocated, but
> still works on the code some. We're going to our best to enforce the
> standard on the third guy.
IME, it is tough to enforce standards in general and, especially, coding
standards in particular on anyone who doesn't want them. I would try to
eliminate style issues from such a standard. If readability is an
issue, then buy or write a syntax beautifier to be applied to all code
just before it is checked in. At least then you are not in the position
to telling the third guy to /write/ code your way.
Another problem with coding standards is that it is difficult to
demonstrate that they are actually doing any good at all, much less
quantifying the benefits relative to other process improvements one
might make. For that reason standards should usually evolve piecemeal
over time as one addresses particular problems.
For example, I don't know MODL, but in C/C++ one can have errors due to
writing "=" in conditional expressions rather than "==". As it happens,
if you enclose the condition in parentheses most compilers will issue a
warning in the first case, which makes it easy to avoid an escape. One
could include using such parentheses in a monolithic coding standard
initially.
At that point you have no idea whether the extra keystrokes are worth
the effort. (They probably are justified because this is a fairly
common problem IME, but you don't /know/ that about your shop's people.)
If there is a political problem in having the standard, you may well
lose more time arguing about it than you spend in debug and rework.
So a better solution is to add that practice incrementally to an
existing standard _when you have data in hand to quantify the benefit_.
At that point the naysayer position becomes untenable for that
particular standard element. So if you or your similarly inclined
fellow developer feels there is a problem, you can collect the data to
verify that.
Of course collecting data is a whole other problem. I would regard
providing a noninvasive infrastructure for that as being far more
important over the long term than a coding standard. Once you have data
to quantify process improvement it gets a whole lot easier to do process
improvement across the whole shop and process. IOW, if you are going to
pick battles to fight, invest in the most important ones.
*************
There is nothing wrong with me that could
not be cured by a capful of Drano.
H. S. Lahman
h...@pathfindermda.com
Pathfinder Solutions -- Put MDA to Work
http://www.pathfindermda.com
blog: http://pathfinderpeople.blogs.com/hslahman
(888)OOA-PATH
Bjorn Reese
> So a better solution is to add that practice incrementally to an
> existing standard _when you have data in hand to quantify the benefit_.
Although I agree with this, oftentimes, however, people fall into the
trap of adding rules based on a single incident. This is due to a
psychological phenomenon called vividness, where we overemphasize
incidents that are emotionally interesting, concrete and image-
provoking, or close to us in time and place.
So, before adding a rule, you must determine if the the problem is
likely to occur frequently or cause major difficulties -- or whatever
criteria you use for your coding standard.
--
mail1dotstofanetdotdk
kramer.n...@gmail.com
with the third person. He's not going to continue to do a lot of
coding, so it should be okay. The people who are likely to be spending
time working with this code have not yet been hired. That's why we
need to establish standards and make the existing code comply with
those standards as much as practicable (with low risk), so that we can
go on with good practices.
As to limiting the stylistic elements of the standard until they become
necessary, I'm not sure about that. The thing that I'm certain needs
doing is providing a standard for comments. None of this code was
commented when I came here and it is really difficult to read (and I'm
in the process of adding comments). As to the actual style of the
code, that's also more to promote readability than to avoid errors. It
just seems to me that code is easier to read when it is written in a
consistent style (naming conventions seem particularly pertinent here).
As to automated testing, the seems like a great idea, but it still
seems like too much work.
> You can 'lint' the language by parsing it into a structure in memory, then
> sweeping the structure with visitors; the Interpreter Design Pattern.
Philp: I'm not sure what you mean by this. Could you elaborate.
Anyway thanks for the comments. I'll be happy to read more. Thanks
especially for the nice links.
H. S. Lahman
Sure. But I would argue that is part of the data one needs to collect
for the quantification. All the process improvement frameworks provide
guidelines for avoiding this sort of pitfall.
H. S. Lahman
> Thanks for the help guys. I think that I overemphasized the problem
> with the third person. He's not going to continue to do a lot of
> coding, so it should be okay. The people who are likely to be spending
> time working with this code have not yet been hired. That's why we
> need to establish standards and make the existing code comply with
> those standards as much as practicable (with low risk), so that we can
> go on with good practices.
My counter would be that one should hire people who are already
culturally on board for process improvement. Then one can incrementally
add standards on a demonstrated need basis as people come on board.
>
> As to limiting the stylistic elements of the standard until they become
> necessary, I'm not sure about that. The thing that I'm certain needs
> doing is providing a standard for comments. None of this code was
> commented when I came here and it is really difficult to read (and I'm
> in the process of adding comments). As to the actual style of the
> code, that's also more to promote readability than to avoid errors. It
> just seems to me that code is easier to read when it is written in a
> consistent style (naming conventions seem particularly pertinent here).
With people coming on board you are still likely to have style issues.
For example, I know agile developers who will tell you that one should
not use comments at all because they tend to become obsolete during
maintenance and refactoring. Rather one should depend upon things like
good naming conventions, macros, standard idioms, etc. for making the
code self-documenting.
That segues to quantification. How do you know the quality of comments
is your Fat Rabbit problem? Or whether the problem lies more in poor
comment maintenance rather than the initial comment form and content?
I really think you will need hard data to convince new hires that your
standard is the way they should write code. So in the meantime I would
(a) collect some data to prove your intuition is correct and comments
are the Fat Rabbit and (b) use a beautifier to make the code readable
before it is checked in until you can justify specific standard elements.
> As to automated testing, the seems like a great idea, but it still
> seems like too much work.
I have to strongly disagree here. Investment in a test harness for
automation will pay huge dividends over time in reliability and effort.
It ensures full regression suites are run, minimizes test results
analysis, minimizes developer interactions, and allows the regression
suites to be run much more often. Running full regression suites more
often is crucial to identifying errors more quickly before one gets a
cascade effect of errors breeding errors.
Marco
> >
> > As to limiting the stylistic elements of the standard until they become
> > necessary, I'm not sure about that. The thing that I'm certain needs
> > doing is providing a standard for comments. None of this code was
> > commented when I came here and it is really difficult to read (and I'm
> > in the process of adding comments). As to the actual style of the
> > code, that's also more to promote readability than to avoid errors. It
> > just seems to me that code is easier to read when it is written in a
> > consistent style (naming conventions seem particularly pertinent here).
>
> With people coming on board you are still likely to have style issues.
> For example, I know agile developers who will tell you that one should
> not use comments at all because they tend to become obsolete during
> maintenance and refactoring. Rather one should depend upon things like
> good naming conventions, macros, standard idioms, etc. for making the
> code self-documenting.
You still need some comments, just not redundant ones. The existing
unreadable code base is what brought the OP here in the first place.
There are too many "artistes" in this business that think THEIR code is
perfect and doesn't need any comments.
Naming is very important and belongs in your standard, brace placement
is not.
>b) use a beautifier to make the code readable
> before it is checked in until you can justify specific standard elements.
Artistic Style is a reindenter and reformatter of C, C++, C# and Java
source code.
It should work for anything close to C. Try it.
http://www.desy.de/~njwalker/astyle.html
kramer.n...@gmail.com
> culturally on board for process improvement. Then one can incrementally
> add standards on a demonstrated need basis as people come on board.
> With people coming on board you are still likely to have style issues.
> For example, I know agile developers who will tell you that one should
> not use comments at all because they tend to become obsolete during
> maintenance and refactoring. Rather one should depend upon things like
> good naming conventions, macros, standard idioms, etc. for making the
> code self-documenting.
Those things are great except that we have this big bunch of hard to
read, uncommented code that forms the core of our system. Part of my
job is to document (comment) it! In this way, new hires will be able
to read the code more easily. Rewriting the code so that it uses
macros, standard idioms, consistent naming conventions, etc is way too
risky. We can't afford the time to do it and we can't afford to break
anything. The commenting standards that we have are largely just to
get the commentor started.
Also, How do I develop standards for good naming conventions, macros,
and standard idioms? You are right to say that these things should be
done incrementally and they will be, but are there guidleines for doing
them anyway?
> I have to strongly disagree here. Investment in a test harness for
> automation will pay huge dividends over time in reliability and effort.
> It ensures full regression suites are run, minimizes test results
> analysis, minimizes developer interactions, and allows the regression
> suites to be run much more often. Running full regression suites more
> often is crucial to identifying errors more quickly before one gets a
> cascade effect of errors breeding errors.
What are full regression suites? You're right test automation is
greatand we'll automate as much as we can, but being without a
preprocessor/compiler/linker and not having time to build those things,
we are limited with what we can do.
H. S. Lahman
>>>As to limiting the stylistic elements of the standard until they become
>>>necessary, I'm not sure about that. The thing that I'm certain needs
>>>doing is providing a standard for comments. None of this code was
>>>commented when I came here and it is really difficult to read (and I'm
>>>in the process of adding comments). As to the actual style of the
>>>code, that's also more to promote readability than to avoid errors. It
>>>just seems to me that code is easier to read when it is written in a
>>>consistent style (naming conventions seem particularly pertinent here).
>>
>>With people coming on board you are still likely to have style issues.
>>For example, I know agile developers who will tell you that one should
>>not use comments at all because they tend to become obsolete during
>>maintenance and refactoring. Rather one should depend upon things like
>>good naming conventions, macros, standard idioms, etc. for making the
>>code self-documenting.
>
>
> You still need some comments, just not redundant ones. The existing
> unreadable code base is what brought the OP here in the first place.
> There are too many "artistes" in this business that think THEIR code is
> perfect and doesn't need any comments.
> Naming is very important and belongs in your standard, brace placement
> is not.
My point was that using comments is, itself, controversial. If the OP
defines a commenting standard and hires someone who believes in
self-documenting code, there will be a problem. That person will argue
that the standard is not addressing the real problem, which is making
the code itself more readable. That is, the problem with the current
unreadable code will not be fixed with comments.
[FWIW, I agree with you that one still needs comments in the code. The
answer to the synchronization problem is a process that ensures they are
synchronized (e.g., comments are reviewed along with the code).]
H. S. Lahman
>>My counter would be that one should hire people who are already
>>culturally on board for process improvement. Then one can incrementally
>>add standards on a demonstrated need basis as people come on board.
>
>
>>With people coming on board you are still likely to have style issues.
>>For example, I know agile developers who will tell you that one should
>>not use comments at all because they tend to become obsolete during
>>maintenance and refactoring. Rather one should depend upon things like
>>good naming conventions, macros, standard idioms, etc. for making the
>>code self-documenting.
>
>
> Those things are great except that we have this big bunch of hard to
> read, uncommented code that forms the core of our system. Part of my
> job is to document (comment) it! In this way, new hires will be able
> to read the code more easily. Rewriting the code so that it uses
> macros, standard idioms, consistent naming conventions, etc is way too
> risky. We can't afford the time to do it and we can't afford to break
> anything. The commenting standards that we have are largely just to
> get the commentor started.
I am not advocating commentless code. I am simply pointing out that if
you define such a standard, you may have problems later with new hires
who don't agree that is the way to solve the problem.
>
> Also, How do I develop standards for good naming conventions, macros,
> and standard idioms? You are right to say that these things should be
> done incrementally and they will be, but are there guidleines for doing
> them anyway?
All I can suggest is to research one of the process improvement
frameworks (TQM, Baldridge, 6-Sigma, et al). All those approaches offer
similar "cookbook" techniques for doing things like that. However,
using those techniques effectively is nontrivial and requires an
understanding of the entire approach philosophy.
For example, will one build a coding standard one macro or idiom at a
time? Sometimes, when a particular problem is resolved. But usually it
will be done in clusters around specific issues (e.g., class/member
names or iteration structures or memory management or whatever). The
team will use the same defined process for developing any given
"cluster". But how one defines the scope of a "cluster" takes judgment
and experience.
[FWIW, from my own experience I would recommend, "A New American TQM" by
Shiba, Graham, and Walden. But the reality is that any of the
frameworks will work if applied properly.]
>>I have to strongly disagree here. Investment in a test harness for
>>automation will pay huge dividends over time in reliability and effort.
>> It ensures full regression suites are run, minimizes test results
>>analysis, minimizes developer interactions, and allows the regression
>>suites to be run much more often. Running full regression suites more
>>often is crucial to identifying errors more quickly before one gets a
>>cascade effect of errors breeding errors.
>
>
> What are full regression suites? You're right test automation is
> greatand we'll automate as much as we can, but being without a
> preprocessor/compiler/linker and not having time to build those things,
> we are limited with what we can do.
A regression suite is essentially all the tests that have been
accumulated against the requirements. The name comes from the idea that
one doesn't want to just test what one has recently developed or fixed;
one wants to test everything from the past to make sure nothing else got
broken by the current work. For any nontrivial application a regression
suite will typically require at least hours to execute, so automation is
crucial. [Anecdotal data point: for a device driver I worked on (~200
KNCLOC) on the unit test regression suite took overnight to run and the
full suite took about a week on the target platform.]
As a practical matter, shops usually have different levels of regression
tests. For example, one may have unit tests, subsystem tests, software
system tests, and integration (with hardware) tests. Each may have its
own collection of all tests for that purpose. A full regression suite
would be one that included all of the tests from all of the categories.
Marco
kramer.n...@gmail.com wrote:
>
> Those things are great except that we have this big bunch of hard to
> read, uncommented code that forms the core of our system. Part of my
> job is to document (comment) it! In this way, new hires will be able
> to read the code more easily. Rewriting the code so that it uses
> macros, standard idioms, consistent naming conventions, etc is way too
> risky. We can't afford the time to do it and we can't afford to break
> anything. The commenting standards that we have are largely just to
> get the commentor started.
>
> Also, How do I develop standards for good naming conventions, macros,
> and standard idioms? You are right to say that these things should be
> done incrementally and they will be, but are there guidleines for doing
> them anyway?
Start with some existing C guidelines:
http://www.chris-lott.org/resources/cstyle/
http://syque.com/cstyle/index.htm
Adapt to MODL as needed. Cover all important topics in your first
draft.
incrementally apply =>
Enforce for all new code or existing code files that get changed by
more than 25-30%.
mar...@yahoo.com
kramer.n...@gmail.com wrote:
> So we are trying to strike a balance between good practices and easily
> implemented practices. Does any one have any sage words for me in my
> quest? Specifically, does anyone have any thoughts one what should be
> done about the old non-compliant code that needs to be maintained but
> is too large to be entirely rewritten? Also are there any meta-coding
> standards? Any process ideas deciding on a coding standard or
> questions to ask about the code that will illuminate what needs to be
> standardized?
see TIOBE Coding Standard Methodology
sidebar at http://www.tiobe.com/tpci.htm