A piece of code is something that not just performs an action, but it's also something that talks about the coder. This post might not actually be related to just my goto languages ( ie Verilog and SystemVerilog ), but also to all the languages that are out there.
So to give a quick example of what I am exactly referring to, here's a simple Verilog code snippet :
module top; bit a= 1; int m; begin $display( "%d %d", a, m ); $display( "%d %d", a, m ); $display( "%d %d", a, m ); $display( "%d %d", a, m ); $display( "%d %d", a, m ); $display( "%d %d", a, m ); begin a = 5; $display( "%d %d",a,m ); end begin $display( "%d %d",a,m ); begin begin $display( "%d %d",a,m ); $display( "%d %d",a,m ); end $display( "%d %d",a,m ); end end end endmodule
Now, as a newbie to coding and the general code guidelines, this might seem like a simple piece of text. But, to a slightly more experienced eye, this is a different thing entirely. The three main rookie mistakes in this kind of coding style are :
The reason why these are mentioned is that they directly improve the code's readability if managed properly. And readability is one of the major factors that determine a coder's ability to pass on his work to the next person or to reduce the time it would take to review one's own code if reviewed after a long period of time.
Giving indentation or simple spacing to the lines of code can do wonders for your readability. It might seem like a small thing in general, but imagine a code that is thousands of lines long and with absolutely no indentation. For someone who has faced this issue, believe me; it is a nightmare. You could spend hours just moving around figuring out what starts where and ends where with more or less no results.
Another piece of advice would be for those of you who like to use spaces rather than the conventional TAB . It is always a good idea to find out what the norm is in your working group. Personally, I have my group working with 4 spaces tab and since we work with Vim, we also use the tab replacement feature ( it basically replaces the tab with equivalent spaces; this keeps the indentation linear throughout every editor you'll ever use ).
This is sometimes one of the most annoying parts of the code that you'll ever come across. If you are someone who has a habit of writing codes with single lines, then please "STOP". Just because you are writing less code, does not actually mean it's more efficient. A lot of times, it's so difficult to run scripts if you have such compact codes. Not to mention, the pain that you'll be giving if you have a huge nesting hierarchy.
Be efficient with what you write, but also try not to overdo it. Try to use single lines of codes only when they seem absolutely necessary. Otherwise, stick with the scope, it's nice.
Here, is an example of where single line of coding style :
case( X ) 32'd0 : $display( "One minus 1" ); 32'd1 : $display( "Two minus 1" ); 32'd2 : $display( "Three minus 1" ); 32'd3 : $display( "Four minus 1" ); 32'd4 : $display( "Five minus 1" ); 32'd5 : $display( "Six minus 1" ); 32'd6 : $display( "Seven minus 1" ); 32'd7 : $display( "Eight minus 1" ); 32'd8 : $display( "Nine minus 1" ); 32'd9 : $display( "Ten minus 1" ); default: $display( "Nothing Here" ); endcase
Comments are the key to any good code. Be it you who is going to read them or one of your beloved colleagues; anyone would appreciate a good comment.
Writing efficient comments is also an art. The principle rules for writing comments can be listed out in 6 simple points :
Here's an example of some decent comments :
bit crc16_com; // Will be used in CRC16 calculation // Registers used in CRC Calculation bit crc7_com; bit crc32_com; bit crc64_com; // This is the procedural code used for the CRC Calculation initial begin $display( "CRC Calculation Logic" ); crc32_com = CRC32( IN_DATA_X ); end /* CRC7, CRC32, CRC64 are to be used in the following calculations and will give the resulting Cyclic Redundancy Check values for the given inputs. */ initial begin crc7 = CRC7( IN_DATA_A ); crc32 = CRC32( IN_DATA_B ); crc64 = CRC64( IN_DATA_C ); end initial begin $display( "CRCm" ); // Simple CRC Display end
Naming convention plays a very crucial role in how well your code is managed. As the size of your code increases and variables keep piling up, there has to be a good way of keeping all those wild variables managed.
In my industry, the general rule that we follow is that based on the datatype and then the purpose of the variable. We basically have registers and wires/nets data types in Verilog. So, when declaring a register data type, one would usually add a suffix of "_r" and when declaring a net, the suffix is "_w" . Other than this, the other common practices are to declare variables of common category with the same suffix. There are occasionally situations, where you also find prefixes begin used.
bit xcom_r; bit xcom_w; logic shift_rev_r; logic shift_rev_w; logic err_shift_rev_r; logic crc_shift_rev_w; bit crc_com16; bit crc_com7;
The original piece of code, when written with proper indentation and other simpler details, would look something like this :
module top; bit a_temp_val = 1; int m; begin $display( "%d %d", a_temp_val, m ); $display( "%d %d", a_temp_val, m ); $display( "%d %d", a_temp_val, m ); $display( "%d %d", a_temp_val, m ); $display( "%d %d", a_temp_val, m ); $display( "%d %d", a_temp_val, m ); begin a_temp_val = 5; $display( "%d %d",a_temp_val,m ); end begin $display( "%d %d",a_temp_val,m ); begin begin $display( "%d %d",a_temp_val,m ); $display( "%d %d",a_temp_val,m ); end $display( "%d %d",a_temp_val,m ); end end end endmodule
You can actually see how a little bit of spacing and a tiny bit of care can do wonders for the code when it comes to making it more readable.
Now, the thumb rule here, is that your style of writing code should reflect your experience. And even if it doesn't, you'll always be appreciated and looked up to if your code can reduce someone else's review time.