lectures.alex.balgavy.eu

Lecture notes from university.
git clone git://git.alex.balgavy.eu/lectures.alex.balgavy.eu.git
Log | Files | Refs | Submodules

philosophy-of-software-design.html (3920B)

      1 <!DOCTYPE html>
      2 <html>
      3 <head>
      4 <script type="text/javascript" async src="https://cdn.jsdelivr.net/gh/mathjax/MathJax@2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
      5 <link rel="Stylesheet" type="text/css" href="style.css">
      6 <title>philosophy-of-software-design</title>
      7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
      8 </head>
      9 <body>
     10 
     11 <div id="Philosophy of Software Design"><h1 id="Philosophy of Software Design">Philosophy of Software Design</h1></div>
     12 <div id="Philosophy of Software Design-Summary of Design Principles"><h2 id="Summary of Design Principles">Summary of Design Principles</h2></div>
     13 <ul>
     14 <li>
     15 Complexity is incremental, even small things make a difference
     16 
     17 <li>
     18 Working code isn't enough, don't introduce complexity just to finish faster
     19 
     20 <li>
     21 Make continual small investments to improve system design
     22 
     23 <li>
     24 Modules should be deep (provide powerful functionality, yet have simple interfaces)
     25 
     26 <li>
     27 Interfaces should be designed to make most common usage as simple as possible
     28 
     29 <li>
     30 simple interace &gt; simple implementation (for a module)
     31 
     32 <li>
     33 General-purpose modules are deeper
     34 
     35 <li>
     36 Separate general-purpose and special-purpose code
     37 
     38 <li>
     39 Different layers should have different abstractions. If two adjacent layers have similar abstractions, there's probably a probem with class decomposition.
     40 
     41 <li>
     42 Pull complexity downward, make life as easy as possible for the user
     43 
     44 <li>
     45 Define errors (and special cases) out of existence (when they pop up)
     46 
     47 <li>
     48 Design it twice, consider multiple options for each major design decision
     49 
     50 <li>
     51 Comments should describe things that are not obvious from the code
     52 
     53 <li>
     54 Software should be designed for ease of reading, not ease of writing
     55 
     56 <li>
     57 Increments of software development should be abstractions, not features. It's ok to put off an abstraction until it's needed by a feature, but once it's needed, take the time to design it cleanly.
     58 
     59 </ul>
     60 
     61 <div id="Philosophy of Software Design-Summary of red flags"><h2 id="Summary of red flags">Summary of red flags</h2></div>
     62 <ul>
     63 <li>
     64 Shallow module: one whose interface is complicated relative to the functionality it provides
     65 
     66 <li>
     67 Information leakage: when the same knowledge is used in multiple places (e.g. two different classes both understand format of a particular type of file)
     68 
     69 <li>
     70 Temporal decomposition: execution order is reflected in the code structure, which can lead to information leakage
     71 
     72 <li>
     73 Overexposure: if API for commonly used features forces users to learn about other features that are rarely used, it increases cognotive load on the users
     74 
     75 <li>
     76 Repetition: if the same piece of code appears multiple times, you probably haven't found the right abstraction
     77 
     78 <li>
     79 Special-general mixture: when a general-purpose mechanism contains code specialised for a particular use of that mechanism, which makes it more complicated and creates information leakage
     80 
     81 <li>
     82 Conjoined methods: it should be possible to understand each method independently, and if you can't, that's a red flag
     83 
     84 <li>
     85 Comment repeats code: if information in a comment is already obvious from the code, that comment is useless
     86 
     87 <li>
     88 Implementation documentation contaminates interface: when interface documentation describes implementation details that aren't needed to use what's being documented
     89 
     90 <li>
     91 Vague name: if variable/method name is broad enough to refer to different things, it doesn't convey much info to the developer
     92 
     93 <li>
     94 Hard to pick name: if it's hard to find a simple name for variable/method that creates a clear image of the underlying object, the underlying object may not have a clean design
     95 
     96 <li>
     97 Hard to describe: comment describing method/variable should be simple and complete. If that's hard, there may be a problem with what you're describing
     98 
     99 <li>
    100 Nonobvious code: if meaning and behavior of code can't be understood when skimming, it's a red flag.
    101 
    102 </ul>
    103 
    104 </body>
    105 </html>