Code Smells Part 1: Basic Smells

Editor's Notes

• #2: Presenter Readme and Demo Script: Many slides in this presentation use builds. This means that some slides may contain multiple images that are displayed individually based on a mouse click. To view the presentation properly, you must be in slide show mode or reading view. If a slide has a demonstration that requires the LabVIEW development environment, the slide will feature a LabVIEW icon watermark on the left hand side of the slide as a reminder that demo code is available in the presentation LabVIEW project. The location of the demo files is listed in the slide notes. If a slide is not printed here, there are no notes associated with that slide.
• #6: Slide: Common Code Smells Here is a list of common code smells. During the remainder of this presentation, we will look at examples and discuss ways of addressing them.
• #14: Slide: Poor Naming Code smells aren’t just limited to LabVIEW. This slide shows variables in a TestStand sequence file. It illustrates both excessively short identifiers and excessively long identifiers. Ask the audience for some ideas for methods to correct the issue. Possible answers: Use names that help make the purpose of the software evident (self-documenting code) Adopt naming conventions Reasons for adopting naming conventions: Reduce the effort needed to read and understand source code Enable code reviews to focus on more important issues than arguing over syntax and naming standards Enable the use of automated refactoring or search and replace tools with minimal potential for error Enhance clarity in cases of potential ambiguity avoid "name collisions" that might occur when the work of different developers is combined Provide better understanding in case of code reuse after a long period of time
• #15: Slide: Overly Complicated This slide shows overly complex VIs. Build 1: Shows a calculation implemented using nodes on the block diagram. Ask the audience what they would do to correct the issue. Build 2: Shows the code refactored to use a formula node to achieve the same result. There are demo VIs for the first two images. You can run them to show that the output is the same from the original code and the refactored code. The demos are located in 01 – Overly Complicated\Overly Complicated Demo 1.vi and Overly Complicated Demo 1_Formula Node.vi Build 3: Shows another example that is overly complicated. Ask the audience what they would do to correct the issue. (Possible answers: Create a Sub VI to replace the three case structures on the right side of the diagram, use a formula node to simplify the calculations) If needed, Demo VI is located in 01 – Overly Complicated\Overly Complicated Demo 2.vi.
• #16: Slide: Contrived Complexity Build 1: This code was part of a much larger application. Ask the audience if they can easily determine the functionality of the code in the while loop. Open and run the demo VI (Demo is located in 02 - Contrived complexity\Contrived Complexity Demo.vi). If they haven’t already figured it out, tell the audience that the functionality of the loop is to strip the path of the current VI - Which could be greatly simplified by replacing the while loop with the built-in LabVIEW Strip Path function
• #17: Slide: Too Many Modules Build 1: The customer was experiencing problems with RS232 communication. This slide shows a partial listing of the serial communication VIs found on the customer’s test system. Ask the audience for their initial thoughts about this directory listing. Does anything smell here? Build 2: Shows that this customer had 34 VIs for performing serial communication. Should we be surprised they were having problems?
• #18: Slide: Evolution of a Code Smell Build 1: Shows the evolution of a code smell. It shows the VI name, the number of terminals on the connector pane and the number of connected terminals (Connector Density) for the directory shown in the previous slide. Beginning at the bottom, you can see the evolution by reading the VI name and examining the connector density. The evolution is clear as you progress up the list. For example beginning with the VI at the bottom of the list – We have “RS232 Read_Write_withlog.vi” with 7 of 12 connector terminals used. The next VI is “RS232 Read_Write_count.vi” with 8 of 12 terminals used. Some time after creating the first VI, the customer decided that they needed to output the byte count, so they copied and renamed the original VI and connected another output terminal. As their needs evolved, they followed this copy/rename/change connector development model. This example shows how code smells are innocently propagated and get worse over time. Ask the audience what they would do to improve this situation.
• #19: Slide: Duplicate Logic Build 1: Shows a LabVIEW VI with duplicate logic. At least the author did try to be neat…BUT this code illustrates the problems with cut and paste. Point out the that the full block diagram is HUGE because the developer has made a copy of the code for each channel in the system. Mention the LabVIEW Navigation Window shown on the right side of the image in the slide. Demo the Navigation Pane if the audience is not familiar with it (Demo is located in 04 - Duplicate Logic\Navigation Window Demo\Navigation Window Demo.lvproj) (Press Ctrl + shift + N on the block diagram to open the Navigation Window). Ask the audience what they would do to improve this code. (Possible answers: Create a sub VI)
• #20: Slide: Disorganization There are two example block diagrams in the slide. Click through to display each example. Build 1: Shows disorganized code. Build 2: Shows another example of disorganized code. Ask the audience what they would do to improve this code.
• #21: Slide: Breaks Dataflow Build 1: Shows a portion of LabVIEW code that breaks dataflow by overusing global variables. Ask the audience if anything smells here. Tell the audience that you should use variables only when necessary. Use wires to transfer data whenever possible.
• #22: Slide: Outdated Practices The demo VI associated with this slide implements an interactive switch control interface using a polling architecture. (Demo is located in 07 - Outdated Practices\Interactive_Switch_Control.VI). Run the VI to show its functionality, then show the block diagram and note that it uses a polling architecture. Ask the audience what they would do to improve this code (Possible answer: Refactor the code to use an event structure instead of polling.
• #23: Slide: Too Many Parameters Build 1: Shows a VI icon / connector pane. Note that this VI is using the connector pane with 28 terminals – 20 of which are connected. Build 2: Shows what it might look like when you wire this VI on your block diagram. Ask the audience if anything smells here. VIs with this many parameters are difficult to wire. VIs with this many parameters indicate that the VI is doing too much work. Ask the audience how they might correct this. (possible answers: create sub VIs, pass parameters as a cluster)
• #24: Slide: Excessive use of literals A literal is a value that has been hard-coded directly into your source code whose value is obvious when inspecting the code. Build 1: The image on this slide shows a VI for performing serial write and read to a COM port. Point out that most of the inputs to the VISA Configure Serial Port VI are implemented as literals. Ask the audience they can name some disadvantages to this approach.
• #25: Slide: Cyclomatic Complexity Cyclomatic complexity measures the number of linearly independent paths in the block diagram code. It gives an indication on the amount of branching in the code and subsequently the recommended number of tests cases required to validate VI functionality. The demo VI associated with this slide has a cyclomatic complexity of 30. Code with high cyclomatic complexity is difficult to debug and maintain. Move some decision points (case structures, loops, etc.) into sub-VIs so that each module can be tested independently, and easily maintained. (Demo is located in 10 - Cyclomatic Complexity\Cyclomatic Complexity Demo.vi)