Creating a team specific style guide Peter Horn NER Staff Applications Engineering Specialist National Instruments UK CLA CTA About the Session Author Peter Horn has worked for National Instruments UK for 13 years in a variety of roles ID: 1043705
Download Presentation The PPT/PDF document "LabVIEW Style Guidelines" is the property of its rightful owner. Permission is granted to download and print the materials on this web site for personal, non-commercial use only, and to display it on your personal computer provided you do not modify the materials and that you retain all copyright notices contained in the materials. By downloading content from our website, you accept the terms of this agreement.
1. LabVIEW Style GuidelinesCreating a team specific style guidePeter HornNER Staff Applications Engineering Specialist, National Instruments UKCLA, CTA
2. About the Session AuthorPeter Horn has worked for National Instruments UK for 13 years in a variety of rolesHas been working in the Applications Engineering Specialist group for 4 years, supporting large customers with complex LabVIEW, TestStand and VeriStand applicationsIs a Certified LabVIEW Architect and Certified TestStand ArchitectHas presented at 3 CLA Summits on topics such as Assertions in LabVIEW, .NET and TestStand custom step process standardisation
3. AgendaLabVIEW Style GuidelinesSome ideas on what should be included in a team specific style guideline?How to use that style guideline to ensure maintainable codeUsing VI Analyzer as a tool to speed up the review process
4. Establishing Style GuidelinesWhy do we need Style Guidelines?Inconsistent approaches to development and to user interfaces can be a problem when multiple developers work on a project because each developer has his own style of developmentInconsistent style techniques create software that looks badInconsistent style also makes software difficult to maintainLimit choice for developers to ensure they use best practices for codingMany decisions are probably OK, as long as the implementation is consistent then future developers will be able to understand and maintain the code
5. The LabVIEW Style Checklist The LabVIEW Style Checklist (LabVIEW Help) provides some style recommendations and checklists to use when working on LabVIEW projects.
6. The LabVIEW Style ChecklistFront PanelUser Interface Front PanelFront Panel DialogConditionalNon-User Interface Front PanelsBlock DiagramLabVIEW ClassesLabels and CommentsSize and LocationProgrammingCorner CasesError HandlingPerformanceConditionalSubVIsAPI DesignOrganisationProject OrganizationDistributing Source CodeOS Folder StructureLibrary UsageReuse ConsiderationsTarget SpecificReal TimeHandling DataInitialization and ShutdownMiscellaneousFPGAFPGA Host InterfaceFPGA Resource Usage
7. Team Style Guide and Review Process ConsiderationsStyle Guide ItemsCommon starting points/templatesDevelopment team skill level and structurePrioritise often conflicting project pressuresSoftware lifecycle/development processSoftware test methodology (and release process)Design language and documentationFile and procedure naming conventionsReadability, scalability and maintainabilityStyle guide scopeAcceptable exceptionsReview processDesign stageCoding stageReview stageReview meeting guidelines
8. Common Starting Points/TemplatesFred loves QMH and building nice UI’s based on a publish/subscribe architectureBarney is a fresh graduate and has heard an FGV is the solution to everything!Wilma recently sat the Actor Framework course and wants a chance to use that knowledgeBetty is new to LabVIEW and just wants to use a state machine
9. Common Starting Points/TemplatesFred loves QMH and building nice UI’s based on a publish/subscribe architectureBarney finds the Delacor DQMH (DQMH) really easy to understand and fast to use, so wants to use this for all his applicationsWilma recently sat the Actor Framework course and wants a chance to use that knowledgeBetty is new to LabVIEW and just wants to use a state machineBamm-Bamm is a fresh graduate and has heard an FGV is the solution to everything!
10. Development Team Skill Level and StructureDerekIntegration Engineer8 years LV exp.CLA
11. Prioritise Often Conflicting Project PressuresQuality is never an acceptable compromise for long term codeExceptions to style for valid reasons should be noted in comments and instances loggedDetermine decision making procedure for instances when compromises must be madeProject DevelopmentQualityProject ScopeDelivery TimeBudget/Resources
12. Informal requirementsLow reuseGet to the result quicklyTest immediate functionalityCode and forgetSoftware Lifecycle and Development ProcessFormal requirements documentationReuse libraries with defined ownersCode for readability and robustnessBuild formal test procedureDefine a maintenance scheduleShort term codeSingle project/PoCLong term code Multi-Decade Support
13. Software Lifecycle and Development Process
14. Software Test MethodologyOnce you’ve decided on a software lifecycle process, you can decide on how you want to test the softwareUnit testing with NI Unit Test Framework or JKI VI TesterIntegration testing Either (or something else) is probably fine as long as you have a planned test procedure and stick to itUnit testing has the advantage that if you update a module, you can just rerun the automatic tests to confirm it still worksUnit testing can be built into an automated build process using Jenkins or similarUnit testing requires a different approach to code development – following Test Driven Design (TDD) principles
15. Design Language and DocumentationFind a way to describe and document the high level architecture and core modulesWhiteboard diagramUMLOther…..Define code documentation guidelinesNumber of comments and comment length can be checked with VI AnalyserToo much documentation as bad as none – nobody wants to read an essayPut in place a process to ensure documentation is updated when the code is
16. File and Procedure Naming ConventionsFind a naming convention that works for you and apply itLabVIEW files and vi objects (controls/indicators/constants) should be easy to identify from their name and position in the projectGood variable/vi/class/library/method names are a key element of program readabilityNames should be as specific as possible. Names that are general enough to be used for more than one purpose are usually bad namesAbbreviations are rarely needed with modern programming languagesLabVIEW has the advantage over text based languages that spaces are easy to use in names – take advantage of that fact to make names easier to understandCode is read far more times than it is written, be sure that naming conventions favour read-time convenience over write-time convenienceCheck out Code Complete by Steve McConnell, chapter 11 on “The Power of Variable Names” for a lot more detail about naming conventions. The principles apply to all files and objects in code
17. Readability, Scalability and MaintainabilityApplying these principles takes time and investmentMake the decision on where and how to apply them for maximum benefitIf you always shoot for 100% reuse and perfect code – you’ll never get anything doneThoughts…..For planned modules, the reuse need should be known so you can make the decision on how to write the codeFor unplanned modules, code for 1 or infinity
18. Style Guide ScopeWhat to include in the style guide and what to leave open to interpretation by developers?VI’s – obviously!Classes and Type Definitions - probablyDocumentation – probablyDepends how much and how extensive it will beProject Layout – yes! A tidy project is a happy projectLong tail of things…Issue tracking process and structureSource code control commit messagesCode review process and documentationRequirements layout and change management
19. Code for 1 or infinityIf truly building for an unmaintained single use – get it working and move on!Short term firefighting – ALWAYS go back and refactor!First step to spaghetti code……Prototype/PoC codeNEVER use this code in a deployed systemOthers may make sense for youMake sure these are exceptionsNot the rule, or you get this!A LOW RISK APPROACH SHOULD BE TAKEN HERE – OFTEN BEST TO BAN THESE SHORTCUTS TOTALLY TO AVOID THE EFFECTS LEAKING INTO DEPLOYED/CRITICAL CODE!Acceptable exceptions
20. Review ProcessDetermine a cadence/trigger for reviewsPreset points in a projectEvery X weeks/SCC commitsPrerequisitesVI Analyser tests should have been run and passedIdeally check code out of SCC on to a clean PC to check dependenciesRelease processFor critical code – do not release until it has passed the review!Above all – reviews need to be open and constructiveEncourage developers to share their codes weak points and discuss ideas for improvement
21. LabVIEW VI Analyzer Toolkit Add-on toolkit for LabVIEWAutomate static code analysis with configurable testsPerformanceStyle Interactively inspect failuresMore than 90 included testsAllows custom tests to be writtene.g. Check all clusters are typedefsGenerate custom reports
22. Why should I use the VI Analyzer?The VI Analyzer improves the quality of your code by analyzing block diagrams and front panels to see if team specific style guide best practices are followed.Use the VI Analyzer interactively to detect issues during your daily programming work.Use the VI Analyzer programmatically to detect issues as part of a nightly build of your LabVIEW application.Check out the VI Analyzer Enthusiasts Community Forum for ideas and prebuilt testshttp://forums.ni.com/t5/VI-Analyzer-Enthusiasts/ct-p/7021
23. Final Discussion Questions and Next StepsEverything mentioned in this session is a time investmentIt will cost time (and therefore money) in the short-termThat investment will pay for itself many times over long-termTalk to management to get buy inCreate a style guide for your team – even if you’re the only one who uses it. You will see the benefit!What will you put in there?Start reviewing code if you’re not already. This is probably the lowest cost yet biggest improvement to code quality you can makeRemember!!!Lack of time is not an excuse – this should save time long termQuality is never an acceptable compromise for deployment code. Time, budget and scope are the other factors which can be compromised on
24. ReferencesBrian Powell – athenahealthSoftware Engineering best practises on CLA CommunityFabiola De la Cueva – DelacorTechnical Wealth vs Technical Debt session from European CLA Summit 2017Steve McConnell – ConstruxCode Complete author – much information taken throughout the slidesSteve Watts – SSDCRandom Ramblings on LabVIEW Design – A Tidy Project is a Happy Project
25. Thank You!