Style & Design Principles
Chapter 01: Code Style & Structure
Nick Prühs
About Me
“Best Bachelor“ Computer Science
Kiel University, 2009
Master Games
Hamburg University of Applied Sciences, 2011
...
First Things First
• At npruehs.de/teaching you‘ll always find
• these slides
• solutions to all assignments
• Ask your qu...
Objectives
• To get an idea of good code style and structure in
general
• To understand the importance of consistent namin...
What is “good code”?
• Straight-forward and obvious
• You’ll spend far more time reading code than writing.
• You’ll spend...
How to achieve “good code”?
Source: http://xkcd.com/844/ 6 / 78
How to achieve “good code”?
• Pair programming
• Code Reviews
• Client-first programming, Test-driven development
• Refact...
Naming Conventions
• Greatly increase readability and usability
• Differ from language to language
• We’ll take a look at ...
C# Capitalization
• PascalCasing
• Namespaces
• Types
• Member Names
• camelCasing
• Method Parameter Names
9 / 78
Capitalization of Acronyms
• Both characters of two-character acronyms
• Example: IO
• Only first character of three-chara...
Word Choice
• Easily readable:
• HorizontalAlignment instead of AlignmentHorizontal
• Favor readability over brevity:
• Ca...
Namespace Names
<Company>.<Product>.<Feature>.<SubNamespace>
• Plural names where appropriate
• Example: System.Collection...
Type Names
• Nouns for classes and structs
• Example: List, Vector
• Derived classes can end with name of base class
• Exa...
Member Names
• Verbs for methods and events
• Example: AddComponent, ComponentAdded
• Nouns or adjectives for fields
• Exa...
Boolean Trap #1
• Be positive!
• Enabled = true instead of Disabled = false
• CaseSensitive = true instead of CaseInsensit...
Tabs vs. Spaces
• Holy war between two fractions of programmers
• Some are for tabs…
• Seperation of visual representation...
Tabs vs. Spaces
• Most important rule:
Stay consistent.
• … or it might even blow up your version control.
17 / 78
Tabs vs. Spaces
„That said, only a moron would use tabs to format
their code.”
- Jeff Atwood
18 / 78
Tools – StyleCop
• Analyzes C# source code to enforce a set of style
and consistency rules
• Helps developers avoid common...
Tools – StyleCop
StyleCop Settings Dialog in Visual Studio 2012 20 / 78
Tools – StyleCop
Part of a StyleCop Settings File
<StyleCopSettings Version="105">
<GlobalSettings>
<StringProperty Name="...
Tools – StyleCop
StyleCop Warnings in Visual Studio 2012 22 / 78
Tools – Resharper
• Static code analysis
• Many, many shortcuts and quick fixes
• Improved refactoring
• Improved search f...
Tools – Resharper
R# Static Code Analysis in Visual Studio 2012
24 / 78
Tools – Resharper
R# Suggestions in Visual Studio 2012
25 / 78
Tools – Resharper
R# Suggestions in Visual Studio 2012
26 / 78
Tools – Resharper
R# Suggestions in Visual Studio 2012
27 / 78
Tools – Eclipse
Eclipse Java Code Style Clean Up Settings
28 / 78
Tools – Eclipse
Eclipse Java Code Style Clean Up Settings
29 / 78
Type Design – Class vs. Struct
Make a type a struct instead of a class if it…
• Logically represents a single value,
• Has...
Type Design – Class vs. Struct
Make a type a struct instead of a class if it…
• Logically represents a single value,
• Has...
Type Design – Class vs. Struct
Make a type a struct instead of a class if it…
• Logically represents a single value,
• Has...
Type Design – Class vs. Struct
Make a type a struct instead of a class if it…
• Logically represents a single value,
• Has...
Type Design – Class vs. Struct
Make a type a struct instead of a class if it…
• Logically represents a single value,
• Has...
Type Design – Class vs. Interface
• Use interfaces for polymorphic value type
hierarchies
• Example: IComparable, IConvert...
Type Design – Class vs. Interface
36 / 78
Type Design – Class vs. Interface
• Favor (abstract) classes over interfaces
• Adding members to an interface is a breakin...
Type Design – Enums
• Favor enums over static constants
• Provide a zero value for simple enums (e.g. None)
• Don’t use en...
Member Design –
Property vs. Method
Make a member a method instead of a property if
it…
• Is significantly slower than a f...
Member Design – Properties
• Preserve previous value if a property setter throws
an exception
• Don’t throw exceptions fro...
Gotcha!
Don‘t throw exceptions from
static constructors!
41 / 78
Member Design – Methods
• Shorter overloads should simply call longer ones
• public int IndexOf(string s)
• public int Ind...
Member Design – Extensions
Use an extension method, if ...
• It adds functionality relevant to every
implementation of an ...
Member Design –
Operator Overloads
• Make sense for types that feel like primitive types
• Should be defined symmetrically...
Member Design –
Parameters
• Use the least derived required paramter type
• Validate all arguments
• params keyword is use...
Boolean Trap #2
Guess what this code means?
widget.repaint(false);
46 / 78
Boolean Trap #2
Guess what this code means?
widget.repaint(false);
• Function argument is called immediate
• true means im...
Boolean Trap #3
Guess what this code means?
var opacitySlider = new Slider(true);
48 / 78
Boolean Trap #3
Guess what this code means?
var opacitySlider = new Slider(true);
• Function argument is called horizontal...
Boolean Trap #4
Guess what this code means?
stackView.updateHeight(false);
50 / 78
Boolean Trap #4
Guess what this code means?
stackView.updateHeight(false);
• Immediate or not?
• Don‘t update height?
• Up...
Boolean Trap #5
The more, the merrier!
event.initKeyEvent("keypress", true, true, null, null, false, false, false, false, ...
Exceptions
• Help you deal with any unexpected or exceptional
situations that occur when a program is running
• Exceptions...
Benefits of Exceptions
• Integrate well with object-oriented languages
• Does not require changing the method signature
• ...
Gotcha!
Don’t return error codes!
55 / 78
Exception Design
• Exceptions provide consistent error reporting
• No bool return value required
• No HRESULT
• No GetLast...
Throwing Exceptions
• Throw the most specific exception that makes
sense.
• ArgumentException
• ArgumentNullException
• Pr...
Handling Exceptions
• Use a try block around the statements that might
throw exceptions.
• Once an exception occurs in the...
Handling Exceptions
Unhandled exception reported by Microsoft Visual Studio 2012
59 / 78
Exception Best Practice
60 / 78
Exception Best Practice
• Do not catch an exception unless you can handle it
and leave the application in a known state.
•...
Gotcha!
Never use empty catch blocks!
62 / 78
Common Exceptions
• Thrown by your application or the framework
• InvalidOperationException
• ArgumentException
• Argument...
Collection Design
• Inherit from Collection<T>,
ReadOnlyCollection<T> or
KeyedCollection<TKey, TItem>
• Implement IEnumera...
Gotcha!
Don’t implement ICloneable!
65 / 78
The interface ICloneable
• Contract doesn’t define whether cloning an object
returns a deep or shallow copy
• Define your ...
Hint
Implement IEquatable<T>
on value types!
67 / 78
The interface IEquatable
• Defines a method for determining equality of
object instances
• Implement on value types to pre...
Hint
Implement IComparable<T>
where it makes sense!
69 / 78
The interface IComparable
• Defines a type-specific comparison method for
ordering or sorting type instances.
• Override <...
Equals, GetHashCode &
ToString
• If Object.Equals returns true for any two objects,
GetHashCode must return the same value...
Gotcha!
GetHashCode must return the
exactly same value across the
lifetime of an object!
72 / 78
Assignment #1
1. Field Declaration
What’s wrong with the following declaration for the
count of items in a collection?
pri...
Assignment #1
2. Vector Type
Implement a type for a two-dimensional vector with
integer coordinates!
74 / 78
Assignment #1
3. Direction Type
Implement a type for cardinal directions!
75 / 78
Assignment #1
4. Grid Type
1. Implement a type for a generic two-dimensional grid!
2. Add support for iteration, indexing ...
References
• Stack Overflow. What does a good programmer's code look
like? http://stackoverflow.com/questions/366588/what-...
Thank you for your attention!
Contact
Mail
dev@npruehs.de
Blog
http://www.npruehs.de
Twitter
@npruehs
Github
https://githu...
Upcoming SlideShare
Loading in …5
×

Style & Design Principles 01 - Code Style & Structure

1,047 views

Published on

Chapter 01 of the lecture Style & Design Principles taught at SAE Institute Hamburg.

Introduction to naming conventions, type and member design, exception design and common .NET interfaces.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,047
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
23
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Style & Design Principles 01 - Code Style & Structure

  1. 1. Style & Design Principles Chapter 01: Code Style & Structure Nick Prühs
  2. 2. About Me “Best Bachelor“ Computer Science Kiel University, 2009 Master Games Hamburg University of Applied Sciences, 2011 Lead Programmer Daedalic Entertainment, 2011-2012 Co-Founder slash games, 2013 2 / 78
  3. 3. First Things First • At npruehs.de/teaching you‘ll always find • these slides • solutions to all assignments • Ask your questions – any time! • Each lecture will close with • further reading • an optional assignment • Contact me any time at dev@npruehs.de! 3 / 58
  4. 4. Objectives • To get an idea of good code style and structure in general • To understand the importance of consistent naming and code conventions • To learn how to use common tools to write good code more easily 4 / 78
  5. 5. What is “good code”? • Straight-forward and obvious • You’ll spend far more time reading code than writing. • You’ll spend much time reading code you didn’t write. • Loose coupling • Well tested • Reused code • Efficient (?) 5 / 78
  6. 6. How to achieve “good code”? Source: http://xkcd.com/844/ 6 / 78
  7. 7. How to achieve “good code”? • Pair programming • Code Reviews • Client-first programming, Test-driven development • Refactoring • Unit Testing • Great tools • Static code analysis 7 / 78
  8. 8. Naming Conventions • Greatly increase readability and usability • Differ from language to language • We’ll take a look at C#, but many guidelines apply to other languages as well. 8 / 78
  9. 9. C# Capitalization • PascalCasing • Namespaces • Types • Member Names • camelCasing • Method Parameter Names 9 / 78
  10. 10. Capitalization of Acronyms • Both characters of two-character acronyms • Example: IO • Only first character of three-character acronyms • Example: Xml, Html • Never for camelCased identifiers (such as parameters) 10 / 78
  11. 11. Word Choice • Easily readable: • HorizontalAlignment instead of AlignmentHorizontal • Favor readability over brevity: • CanScrollHorizontally instead of ScrollableX • No underscores • No Hungarian notation • No abbreviations • Abbreviations don’t work well with IDEs. • Semantic names • GetLength instead of GetInt 11 / 78
  12. 12. Namespace Names <Company>.<Product>.<Feature>.<SubNamespace> • Plural names where appropriate • Example: System.Collections • Don’t use the same name for namespace and type • Don’t use common names such as Element, Component 12 / 78
  13. 13. Type Names • Nouns for classes and structs • Example: List, Vector • Derived classes can end with name of base class • Example: ArgumentException • Adjectives for interfaces • Prefix interface names with ‘I’ • Example: IComparable • Use descriptive names for type-parameters • Dictionary<TKey, TValue> instead of Dictionary<K, V> • Singular names for non-flags enums • Color instead of Colors 13 / 78
  14. 14. Member Names • Verbs for methods and events • Example: AddComponent, ComponentAdded • Nouns or adjectives for fields • Example: Duration, Invulnerable • Nouns for properties • Plurals for collections • Items instead of ItemList 14 / 78
  15. 15. Boolean Trap #1 • Be positive! • Enabled = true instead of Disabled = false • CaseSensitive = true instead of CaseInsensitive = false 15 / 78
  16. 16. Tabs vs. Spaces • Holy war between two fractions of programmers • Some are for tabs… • Seperation of visual representation from data • Customizable • Faster • Specifically meant for indentation • … while others are for spaces. • Always one column • Supported by IDEs anyway 16 / 78
  17. 17. Tabs vs. Spaces • Most important rule: Stay consistent. • … or it might even blow up your version control. 17 / 78
  18. 18. Tabs vs. Spaces „That said, only a moron would use tabs to format their code.” - Jeff Atwood 18 / 78
  19. 19. Tools – StyleCop • Analyzes C# source code to enforce a set of style and consistency rules • Helps developers avoid common pitfalls and mistakes • Settings file can be checked in to version control 19 / 78
  20. 20. Tools – StyleCop StyleCop Settings Dialog in Visual Studio 2012 20 / 78
  21. 21. Tools – StyleCop Part of a StyleCop Settings File <StyleCopSettings Version="105"> <GlobalSettings> <StringProperty Name="MergeSettingsFiles">NoMerge</StringProperty> <CollectionProperty Name="RecognizedWords"> <Value>Bresenham</Value> <Value>Dijkstra</Value> <Value>Endre</Value> <Value>Fredman</Value> <Value>multigraph</Value> <Value>Stee</Value> <Value>Tarjan</Value> <Value>Tarjan's</Value> <Value>unweighted</Value> </CollectionProperty> </GlobalSettings> <Analyzers> <Analyzer AnalyzerId="StyleCop.CSharp.DocumentationRules"> <Rules> <Rule Name="DocumentationTextMustContainWhitespace"> <RuleSettings> <BooleanProperty Name="Enabled">False</BooleanProperty> </RuleSettings> </Rule> <Rule Name="ConstructorSummaryDocumentationMustBeginWithStandardText"> <RuleSettings> <BooleanProperty Name="Enabled">False</BooleanProperty> </RuleSettings> </Rule> 21 / 78
  22. 22. Tools – StyleCop StyleCop Warnings in Visual Studio 2012 22 / 78
  23. 23. Tools – Resharper • Static code analysis • Many, many shortcuts and quick fixes • Improved refactoring • Improved search features • Code templates 23 / 78
  24. 24. Tools – Resharper R# Static Code Analysis in Visual Studio 2012 24 / 78
  25. 25. Tools – Resharper R# Suggestions in Visual Studio 2012 25 / 78
  26. 26. Tools – Resharper R# Suggestions in Visual Studio 2012 26 / 78
  27. 27. Tools – Resharper R# Suggestions in Visual Studio 2012 27 / 78
  28. 28. Tools – Eclipse Eclipse Java Code Style Clean Up Settings 28 / 78
  29. 29. Tools – Eclipse Eclipse Java Code Style Clean Up Settings 29 / 78
  30. 30. Type Design – Class vs. Struct Make a type a struct instead of a class if it… • Logically represents a single value, • Has a valid state if all data is set to zero, • Has an instance size < 16 bytes, • Is Immutable, and • Won’t have to be boxed frequently 30 / 78
  31. 31. Type Design – Class vs. Struct Make a type a struct instead of a class if it… • Logically represents a single value, • Has a valid state if all data is set to zero, • This is the case for array initialization, for example. • Has an instance size < 16 bytes, • Is Immutable, and • Won’t have to be boxed frequently 31 / 78
  32. 32. Type Design – Class vs. Struct Make a type a struct instead of a class if it… • Logically represents a single value, • Has a valid state if all data is set to zero, • Has an instance size < 16 bytes, • Value type assignments copy all values • Is Immutable, and • Won’t have to be boxed frequently 32 / 78
  33. 33. Type Design – Class vs. Struct Make a type a struct instead of a class if it… • Logically represents a single value, • Has a valid state if all data is set to zero, • Has an instance size < 16 bytes, • Is Immutable, and • Passing (and returning) by value implicitly creates a copy • Value types that can be changed will be confusing! • Won’t have to be boxed frequently 33 / 78
  34. 34. Type Design – Class vs. Struct Make a type a struct instead of a class if it… • Logically represents a single value, • Has a valid state if all data is set to zero, • Has an instance size < 16 bytes, • Is Immutable, and • Won’t have to be boxed frequently • Happens when they’re cast to a interface • Allocated on heap and garbage collected, then! 34 / 78
  35. 35. Type Design – Class vs. Interface • Use interfaces for polymorphic value type hierarchies • Example: IComparable, IConvertible • If an interface does more than exactly one thing, that’s a warning sign. 35 / 78
  36. 36. Type Design – Class vs. Interface 36 / 78
  37. 37. Type Design – Class vs. Interface • Favor (abstract) classes over interfaces • Adding members to an interface is a breaking change! • Seperating of contract from implementation with an interface is a myth… • … whereas doing so with an abstract class is not. 37 / 78
  38. 38. Type Design – Enums • Favor enums over static constants • Provide a zero value for simple enums (e.g. None) • Don’t use enums for open sets • Don’t use flag enums if some combinations can be invalid 38 / 78
  39. 39. Member Design – Property vs. Method Make a member a method instead of a property if it… • Is significantly slower than a field access would be, • Is a conversion operation (such as ToString), • Returns a different result each time it is called, • Has an observable side effect, • Returns a copy of an internal state, or • Returns an array 39 / 78
  40. 40. Member Design – Properties • Preserve previous value if a property setter throws an exception • Don’t throw exceptions from property getters. • Use a method in that case. 40 / 78
  41. 41. Gotcha! Don‘t throw exceptions from static constructors! 41 / 78
  42. 42. Member Design – Methods • Shorter overloads should simply call longer ones • public int IndexOf(string s) • public int IndexOf(string s, int startIndex) • public int IndexOf(string s, int startIndex, int count) • Use descriptive parameter names • Avoid varying names or inconsistent ordering • Make only the longest overload virtual • Allow null to be passed for optional parameters • Default arguments are not CLS-compliant! 42 / 78
  43. 43. Member Design – Extensions Use an extension method, if ... • It adds functionality relevant to every implementation of an interface, or • An instance method would introduce unwanted dependencies 43 / 78
  44. 44. Member Design – Operator Overloads • Make sense for types that feel like primitive types • Should be defined symmetrically • Provide methods with friendly names, as well • Some languages don‘t support operator overloads. 44 / 78
  45. 45. Member Design – Parameters • Use the least derived required paramter type • Validate all arguments • params keyword is useful for arbitrary (but small) numbers of parameters • Pay attention on parameter order • Be aware that null is a valid params array argument 45 / 78
  46. 46. Boolean Trap #2 Guess what this code means? widget.repaint(false); 46 / 78
  47. 47. Boolean Trap #2 Guess what this code means? widget.repaint(false); • Function argument is called immediate • true means immediate painting • false means deferred painting • Better use method overloads or enums! 47 / 78
  48. 48. Boolean Trap #3 Guess what this code means? var opacitySlider = new Slider(true); 48 / 78
  49. 49. Boolean Trap #3 Guess what this code means? var opacitySlider = new Slider(true); • Function argument is called horizontal • true means horizontal slider • false means vertical slider • Better use subclasses! • „Heck, who knows someday you’ll need a diagonal slider!” 49 / 78
  50. 50. Boolean Trap #4 Guess what this code means? stackView.updateHeight(false); 50 / 78
  51. 51. Boolean Trap #4 Guess what this code means? stackView.updateHeight(false); • Immediate or not? • Don‘t update height? • Update width??? 51 / 78
  52. 52. Boolean Trap #5 The more, the merrier! event.initKeyEvent("keypress", true, true, null, null, false, false, false, false, 9, 0); 52 / 78
  53. 53. Exceptions • Help you deal with any unexpected or exceptional situations that occur when a program is running • Exceptions are types that all ultimately derive from System.Exception. • Generated by the common language runtime (CLR), by the .NET Framework or any third-party libraries, or by application code. 53 / 78
  54. 54. Benefits of Exceptions • Integrate well with object-oriented languages • Does not require changing the method signature • Can’t be ignored, whereas error codes can • Exception objects contain detailed information about the error, such as the state of the call stack and a text description of the error. • Possibility of defining an Unhandled Exception Filter (UEF) • Supported by debuggers 54 / 78
  55. 55. Gotcha! Don’t return error codes! 55 / 78
  56. 56. Exception Design • Exceptions provide consistent error reporting • No bool return value required • No HRESULT • No GetLastError • Don’t return error codes. • If your error code is for the developer, add additional information to the exception message instead. • If your error code is for the exception handler, add a new exception type instead. 56 / 78
  57. 57. Throwing Exceptions • Throw the most specific exception that makes sense. • ArgumentException • ArgumentNullException • Provide rich and meaningful error messages. • Introduce a new exception type only if it should be handled differently than existing exception types. 57 / 78
  58. 58. Handling Exceptions • Use a try block around the statements that might throw exceptions. • Once an exception occurs in the try block, the flow of control jumps to the first associated exception handler that is present anywhere in the call stack. • If no exception handler for a given exception is present, the program stops executing with an error message. 58 / 78
  59. 59. Handling Exceptions Unhandled exception reported by Microsoft Visual Studio 2012 59 / 78
  60. 60. Exception Best Practice 60 / 78
  61. 61. Exception Best Practice • Do not catch an exception unless you can handle it and leave the application in a known state. • Do not catch non-specific exceptions, such as System.Exception. • Use a finally block to release resources, for example to close any streams or files that were opened in the try block. 61 / 78
  62. 62. Gotcha! Never use empty catch blocks! 62 / 78
  63. 63. Common Exceptions • Thrown by your application or the framework • InvalidOperationException • ArgumentException • ArgumentNullException • ArgumentOutOfRangeException • Thrown by the CLR • NullReferenceException • IndexOfOutRangeException • StackOverflowException • OutOfMemoryException 63 / 78
  64. 64. Collection Design • Inherit from Collection<T>, ReadOnlyCollection<T> or KeyedCollection<TKey, TItem> • Implement IEnumerable<T> • Allows foreach iteration of your collection. • Implement ICollection<T> or IList<T> where it makes sense • Implement an indexer where it makes sense 64 / 78
  65. 65. Gotcha! Don’t implement ICloneable! 65 / 78
  66. 66. The interface ICloneable • Contract doesn’t define whether cloning an object returns a deep or shallow copy • Define your own Clone method if required, without implementing the interface 66 / 78
  67. 67. Hint Implement IEquatable<T> on value types! 67 / 78
  68. 68. The interface IEquatable • Defines a method for determining equality of object instances • Implement on value types to prevent boxing • Override Object.Equals, == and != operators as well 68 / 78
  69. 69. Hint Implement IComparable<T> where it makes sense! 69 / 78
  70. 70. The interface IComparable • Defines a type-specific comparison method for ordering or sorting type instances. • Override <, >, <= and >= operators as well 70 / 78
  71. 71. Equals, GetHashCode & ToString • If Object.Equals returns true for any two objects, GetHashCode must return the same value for these objects. • Dictionaries, which are implemented as Hashtables in .NET, will place two equal objects in different buckets otherwise, and lookup might fail in that case. • Override ToString wherever it makes sense. • Provides more useful debug output. 71 / 78
  72. 72. Gotcha! GetHashCode must return the exactly same value across the lifetime of an object! 72 / 78
  73. 73. Assignment #1 1. Field Declaration What’s wrong with the following declaration for the count of items in a collection? private int m_itemcnt; 73 / 78
  74. 74. Assignment #1 2. Vector Type Implement a type for a two-dimensional vector with integer coordinates! 74 / 78
  75. 75. Assignment #1 3. Direction Type Implement a type for cardinal directions! 75 / 78
  76. 76. Assignment #1 4. Grid Type 1. Implement a type for a generic two-dimensional grid! 2. Add support for iteration, indexing and copying! 3. Allow comparison of grids by comparing all of their entries! 76 / 78
  77. 77. References • Stack Overflow. What does a good programmer's code look like? http://stackoverflow.com/questions/366588/what- does-a-good-programmers-code-look-like, March 2015. • Cwalina, Abrams. Framework Design Guidelines. 2nd Edition. Addison-Wesley, 2011. • Hidayat. hall of api shame: boolean trap. http://ariya.ofilabs.com/2011/08/hall-of-api-shame- boolean-trap.html, August 24, 2011. • Atwood. Death to the Space Infidels! http://www.codinghorror.com/blog/2009/04/death-to-the- space-infidels.html, April 13, 2009. • MSDN. System Namespace. http://msdn.microsoft.com/en- us/library/System%28v=vs.110%29.aspx, March 2015. 77 / 78
  78. 78. Thank you for your attention! Contact Mail dev@npruehs.de Blog http://www.npruehs.de Twitter @npruehs Github https://github.com/npruehs 78 / 78

×