Coding style

[David M. Palmer]

I am getting started in VHDL, and want to avoid learning bad habits. I
have seen enough bad C/C++ code that I really, really, don't want to
inflict something comparable in VHDL.

I also hope that this question does not provoke a flame war. (By the
way, in C, my brace style is better than yours.)

Is there a 'best style' manual, or at least something that says 'never
do this'.

Capitalization and case of names of signals, constants, entities,
architectures...
Hard tabs vs. spaces? How large is the indent level? The editor
(Xilinx webpack) defaults to hard-tabs at 3 spaces which would be a
bizarre choice in C.
All the arrows aligned vertically with ragged left and right?
All the signals at the beginning of a block followed by the
instantiations, or intermixed?
etc.

Just using the Xilinx webpack ISE I have seen a large variety of styles
from the Coregen, the template generator, the appnotes.

Are there pretty-printers available to fix up what I have done so far?


Style is often gently compelled by tools, but in danger of going off
topic:

What editor and development environment do people use? The Xilinx ISE
webpack is downright primitive compared to what I'm used to using in
the software world. (Yes, I'm complaining that free-as-in-beer
software isn't as nice as I would like. This is not a perjorative
criticism, it is simply a reflection of the amount of polish that gets
applied to something that both developed and used by the same people
vs. something that is not used by its developers*, and for which the
user community is a couple of orders of magnitude smaller.)
*Or worse: if it is developed by its users, who happen
to be hardware people.

Automatic name completion (signals, entities, constants...) would
require a sophisticated parser in the editor or hooks to feed back the
internals of the compiler, and so even though it is standard for Java/C
type development it may not be worthwhile in the smaller VHDL market.
But even a simple split-pane editor would help immensly by letting me
see the names of the signals I've defined in the same file I'm using
them without scrolling back and forth, losing my place.

And there should be a way to automate the tool chain so that after
changing a line in the VHDL, I need to hit only one key in order to get
the changes compiled and installed on the FPGA. There probably is a
way to do this, but my Preferences-Fu is not up to the challenge.

Thank you.

 

[ghelbig]

Everything you want is in the VHDL-mode for EMACS. And it's free.

I'm not as excited about how the source is formatted, so long as it's
all consistent.

 

[Mark Norton]

I am getting started in VHDL, and want to avoid learning bad habits. I
have seen enough bad C/C++ code that I really, really, don't want to
inflict something comparable in VHDL.

Honestly, while I have my preferences for indentation, signal names,
etc, the worst bad habit you can get into is lack of communication. I
cannot count the number of times I've been given someone's old code and
I spend an inordinate amount of time trying to figure out what the coder
was doing when they used some sort of cryptic signal name, some sort of
slick combinatorial reduction (that probably would have happened
correctly anyhow if they'd used a simpler if/elsif construct), a state
machine with 20 states, many of which functionally did the same thing,
and a lack of consistency over entity hierarchy.

* You get at least 32 characters per signal name (possibly more in later
standards... I forget exactly), use them. For a large build, think
early about different signal prefixes for different levels of hierarchy
and blocks and such. There are few things more aggravating than ending
up at the top level with "din" "dout" "din1" "dout1" etc, when you COULD
have "ddrTopBankDMA1_din" "ddrTopBankDMA2_din" "RACEway_din" which
actually gives you an idea where the signal is going.

* Use enumerated types for state machines. A nice features I like in
Xilinx's synthesizer is that it will pick this up and later when it is
optimizing the state machine, it'll tell you in your enumerated type
names which state and flops go together. With Verilog, it doesn't seem
to do this, just uses the numbers even if you do parametric defines.
Which means a trip back through the synthesis file, and then to the
source code when your logic analyzer spits out a number for the state.

* Pick a naming style you like and stick with it. I tend to prefer
underscores (payload_data_we) to CamelCase (payloadDataWE), but that's
just me. I think the whitespace makes it easier to read. Sometimes I
do mix them for complicated names (e.g. the ddrTopBankDMA2_din name)

* Pick a token word vs non-token word style and stick with it. I tend
to lowercase everything except constants. With syntax highlighting, it
is very easy to see tokens, versus literals, versus comments, versus
everything-else.

* Comment everything as if you are expecting hit-by-bus syndrome. That
is to say, if you got hit by a bus tomorrow, taking out everything you
know and all your notes, what would the source code tell the next guy
down the line how it all was put together. In the real world, you very
well could be the "next guy" because you will end up having to remodify
your code two years later and have NO idea what you were thinking
without some commentary.

What editor and development environment do people use? The Xilinx ISE

Since we've been doing Xilinx parts lately almost exclusively, we use
the Xilinx ISE (currently 7.1, but I think we'll probably migrate to 8
as soon as some projects hit a stable point). I like vim
(http://www.vim.org) for my editor personally. I believe it is less
fancy than the Emacs VHDL mode, but it does do split screen, file diffs,
syntax highlighting, indent persistence, and I have a plugin installed
that implements easy way to block off sections into comments. If
someone were to port VHDL mode for Emacs over to a vim script, I'd give
it a shot and see if I liked all the auto-completion and tagging. I
really wish someone would modify the Exuberant CTAGS program for VHDL
sometime because there's a plugin that will handle ctags for VHDL if you
have a way of picking out the names.

A rather handy not-really-a-feature-but-nice of using an external editor
in the Xilinx ISE tool (as of 7.1 anyhow) is that while the design is
going through the build, you can still double click on the file in the
hierarchy pane, and it will launch the editor. If you use the built-in
editor, it will wait until there is a break in a processing point (which
could take awhile) to open up the editor window. So even if you want
nothing fancier than notepad to edit with, it can be worthwhile to
define an external editor.

And there should be a way to automate the tool chain so that after
changing a line in the VHDL, I need to hit only one key in order to get
the changes compiled and installed on the FPGA. There probably is a
way to do this, but my Preferences-Fu is not up to the challenge.

Most build GUI's will do this for you. I know the Active HDL from
Aldec, and Xilinx ISE will let you hit whatever target you want
(Synthesize, Place and Route, Programming File) and it'll build up to
that point.

If your unix-fu is up to snuff, you could set up a Makefile similarly.

Hope this helps.

Best regards,
Mark Norton

 

[Andy]

I generally do not like naming conventions that use capitalization in
languages (such as VHDL) that are not case-sensitive with regards to
identifiers. Thus, mis-capitalized identifiers are different to human
readers, and to some search/replace tools, etc., but not to the VHDL
analyzer.

Among vhdl editors, vhdl-mode in xemacs is widely considered the most
powerful, feature-filled editor available, but it's quirks and user
interface leave many less than pleased. An excellent alternative is
jGrasp (free from University of Auburn). Of all the vhdl-aware editors'
auto-indenting capabilities other than xemacs/vhd-mode, it is the most
powerful that I have seen. It also inserts graphics in the leading
whitespace (in the display) to indicate context and/or control
structures.

Andy

 

[Mike Treseler]

Is there a 'best style' manual, or at least something that says 'never
do this'.

If the code is easy to read and understand, the style is fine.
I prefer to see declarations kept as local as possible.

my preferences:

Capitalization little or none
and case of names of signals my_signal_s
my_variable_v
my_constant_c
entities, file base name
architectures... sim or synth
Hard tabs vs. spaces?

spaces (vhdl-mode does this for you)

How large is the indent level? The editor
(Xilinx webpack) defaults to hard-tabs at 3 spaces which would be a
bizarre choice in C.

I like 3. There are lots of levels

All the arrows aligned vertically with ragged left and right?
All the signals at the beginning of a block followed by the
instantiations, or intermixed?
etc.

vhdl-mode beutify-region works just right.

What editor and development environment do people use?

emacs tied to modelsim.

Automatic name completion (signals, entities, constants...) would
require a sophisticated parser in the editor or hooks to feed back the
internals of the compiler, and so even though it is standard for Java/C
type development it may not be worthwhile in the smaller VHDL market.

emacs vhdl-mode has it already

But even a simple split-pane editor would help immensly by letting me
see the names of the signals I've defined in the same file I'm using
them without scrolling back and forth, losing my place.

And there should be a way to automate the tool chain so that after
changing a line in the VHDL, I need to hit only one key in order to get
the changes compiled and installed on the FPGA. There probably is a
way to do this, but my Preferences-Fu is not up to the challenge.

emacs vhdl-make will cover simulation.

for synthesis I use

make clean;
make;

to get a file list.

-- Mike Treseler

 

[Ralf Hildebrandt]

Mike Treseler wrote:

spaces (vhdl-mode does this for you)

Could you explain, why spaces are better?

I prefer tabs, because of the following:
In any programming or modeling language I try to align my code and my
comments that way, that it looks like a two-column text. Example:

....
if (condition1='1') then -- comment 1
result1<='1';
result2<='0';
elsif (condition2='0' AND condition3='1') then -- comment 2
result1<='0';
result3<='1'; -- comment 3
....

The main reason for this is readability. Moving the comments into the
code makes the code longer. Usually the code is much longer that one
page on my monitor, but I have plenty of horizontal space free.
Furthermore the human eye gets an easier fix, if the structure is more
regular. (And thats another reason for tabs, because I prefer a high
indent level to make the structure of if- and case-branches clearer. 3
spaces are not enough for me.)
Writing this pseudo-two-column text is easier with tabs.


Ralf

 

[Andy]

Ralph,

I think Mike was referring to whether tab or space characters are
better in the file. The same level of indentation is available either
way (i.e. indentations could be 8 spaces instead of tabs).

I prefer spaces myself, since tab stops are changeable in given
editors, and a different tabstop setting may render the code structure
less readable, whereas replacing tab stops with appropriate space
characters always displays the same way in any editor. Many editors
allow the use of the tab key, but automatically insert spaces up to the
next stop. Some editors do not use "tab stops", but just insert a fixed
number of spaces for each tab character.

If you like easy-to-see code structures, etc. I encourage you to give
jGrasp a try; its control structure diagrams shown in the left margin
are very helpful to me, plus they provide visual mouse targets for
expanding collapsing structures in the display. The built-in syntax
checking is a free bonus.

Andy Jones

 

[Ralf Hildebrandt]

Mike Treseler wrote:

spaces (vhdl-mode does this for you)

Could you explain, why spaces are better?

I prefer tabs, because of the following:
In any programming or modeling language I try to align my code and my
comments that way, that it looks like a two-column text. Example:

....
if (condition1='1') then -- comment 1
result1<='1';
result2<='0';
elsif (condition2='0' AND condition3='1') then -- comment 2
result1<='0';
result3<='1'; -- comment 3
....

The main reason for this is readability. Moving the comments into the
code makes the code longer. Usually the code is much longer that one
page on my monitor, but I have plenty of horizontal space free.
Furthermore the human eye gets an easier fix, if the structure is more
regular. (And thats another reason for tabs, because I prefer a high
indent level to make the structure of if- and case-branches clearer. 3
spaces are not enough for me.)
Writing this pseudo-two-column text is easier with tabs.

One big disadvantage is, that tabs may be displayed with different
widths. Thats the reason, why I have formatted the example using spaces
and why my first posting was self-cancelled. - Nevertheless one uses
always the same editor and therefore different widths are not such a big
problem. (Except for code transfers to other people but then I could
also replace the tabs by spaces manually.).


Ralf

 

[Martin Gagnon]

Mike Treseler wrote:



Could you explain, why spaces are better?

I prefer tabs, because of the following:
In any programming or modeling language I try to align my code and my
comments that way, that it looks like a two-column text. Example:

...
if (condition1='1') then -- comment 1
result1<='1';
result2<='0';
elsif (condition2='0' AND condition3='1') then -- comment 2
result1<='0';
result3<='1'; -- comment 3
...

The main reason for this is readability. Moving the comments into the
code makes the code longer. Usually the code is much longer that one
page on my monitor, but I have plenty of horizontal space free.
Furthermore the human eye gets an easier fix, if the structure is more
regular. (And thats another reason for tabs, because I prefer a high
indent level to make the structure of if- and case-branches clearer. 3
spaces are not enough for me.)
Writing this pseudo-two-column text is easier with tabs.

One big disadvantage is, that tabs may be displayed with different
widths. Thats the reason, why I have formatted the example using spaces
and why my first posting was self-cancelled. - Nevertheless one uses
always the same editor and therefore different widths are not such a big
problem. (Except for code transfers to other people but then I could
also replace the tabs by spaces manually.).


Ralf

If you use an advance editor like vim or emacs.. you can use space but
handled like tabs automaticly.. so you press tab and it's automaticly
generate 8 or 4 spaces (depending of your tabs width setting) and
backspace will delete the right number of space depending on the
alignment .. so that's way.. you feel them like tabs when you edit your
code.. and others poeple with any editor and any tabs space setting will
see the same thing as you..

 

[Mike Treseler]

.. so you press tab and it's automatically
generate 8 or 4 spaces (depending of your tabs width setting) and
backspace will delete the right number of space depending on the
alignment .. so that's way.. you feel them like tabs when you edit your
code.. and others poeple with any editor and any tabs space setting will
see the same thing as you..

Yes, I like that tab function,
but not the character.
Real tabs work fine if the designer is the
only one reading the file, but they are a
problem for anyone else trying to read or
print the file.

An advanced editor can take over the tab
key and insert just the right number
of spaces with every press. Now what I
print and what others view is aligned
the same as when I typed it in.

-- Mike Treseler

 

[Kai Harrekilde-Petersen]

Are there pretty-printers available to fix up what I have done so far?

pretty-printers are not a substitute for clear consise programming,
just as revision control isn't a substitute for project management.

What editor and development environment do people use?

I've seen vi, emacs and UltraEdit32 used.


Kai