Coding style

Discussion in 'VHDL' started by David M. Palmer, May 27, 2006.

  1. 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.

    --
    David M. Palmer (formerly @clark.net, @ematic.com)
     
    David M. Palmer, May 27, 2006
    #1
    1. Advertising

  2. David M. Palmer

    Guest

    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.
     
    , May 28, 2006
    #2
    1. Advertising

  3. David M. Palmer

    Mark Norton Guest

    David M. Palmer wrote:
    > 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


    --
    ==============================
    Mark Norton <>
    Concept Development, Inc.
    http://www.cdvinc.com
     
    Mark Norton, May 30, 2006
    #3
  4. David M. Palmer

    Andy Guest

    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
     
    Andy, May 30, 2006
    #4
  5. David M. Palmer wrote:

    > 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
    > constants,

    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
     
    Mike Treseler, May 31, 2006
    #5
  6. Mike Treseler wrote:


    >> Hard tabs vs. spaces?

    > 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
     
    Ralf Hildebrandt, May 31, 2006
    #6
  7. David M. Palmer

    Andy Guest

    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 wrote:
    > Mike Treseler wrote:
    >
    >
    > >> Hard tabs vs. spaces?

    > > 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, Jun 1, 2006
    #7
  8. Mike Treseler wrote:


    >> Hard tabs vs. spaces?

    > 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
     
    Ralf Hildebrandt, Jun 1, 2006
    #8
  9. On 2006-06-01, Ralf Hildebrandt <> wrote:
    > Mike Treseler wrote:
    >
    >
    > >> Hard tabs vs. spaces?

    > > 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

    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..

    --
    Martin
     
    Martin Gagnon, Jun 1, 2006
    #9
  10. Martin Gagnon wrote:

    > .. 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
     
    Mike Treseler, Jun 1, 2006
    #10
  11. "David M. Palmer" <> writes:

    > 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
    --
    Kai Harrekilde-Petersen <khp(at)harrekilde(dot)dk>
     
    Kai Harrekilde-Petersen, Jun 1, 2006
    #11
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Paul Baxter

    style for coding latches

    Paul Baxter, Aug 10, 2003, in forum: VHDL
    Replies:
    7
    Views:
    1,145
    Mike Treseler
    Aug 15, 2003
  2. Willem Oosthuizen

    Coding style to prioritize certain inputs

    Willem Oosthuizen, Sep 2, 2003, in forum: VHDL
    Replies:
    5
    Views:
    501
    Mike Treseler
    Sep 4, 2003
  3. Analog Guy

    Coding style for CPLD vs FPGA

    Analog Guy, Mar 11, 2005, in forum: VHDL
    Replies:
    3
    Views:
    5,457
    Klaus Falser
    Mar 14, 2005
  4. calmar
    Replies:
    11
    Views:
    901
    calmar
    Feb 21, 2006
  5. Ken Varn
    Replies:
    0
    Views:
    473
    Ken Varn
    Apr 26, 2004
Loading...

Share This Page