Please enable JavaScript.

Coggle requires JavaScript to display documents.

330/350 - documentation 330 - Code Documentation & Comments - Coggle…

- - - - explaining why a piece of code exists
      - documenting a design
        that is based on pseudocode
      - cross-referencing related items
  - - - hide poor naming
      - hide failure to extract code blocks into functions
      - hide bad design
      - hide lack of version control, issue tracking, source formatters
      - repeat the code
      - explain straightforward code
      - explain hard to read code that could be simplified
  - - - used for
        
        improving readability
        
        describing a solution
      - used on
        
        large amounts of code
    - - used for
        
        describing a problem
    - - 3 examples
        
        authors
        
        copyright
        
        date of modification
- - - - interface presents a consistent abstraction
      - well-named, name describes its central purpose
      - can be treated as a black-box
        
        abstract to the point that you dont have to think about how its services are implemented
    - - routines' names describe exactly what they do
      - each routine performs one well-defined task
      - parts of each routine that would be better off separated out into their own routines are separated
      - each routine's interface is obvious and clear
    - - type names descriptive enough to help document data declarations
      - variables named well
      - variables used only for the purpose for which they’re named
      - loop counters given better names than i, j, and k
      - well-named enumerated types used instead of makeshift flags or boolean variables
      - named constants used instead of magic numbers or magic strings
      - naming conventions distinguish between type names, enumerated types, named constants, local variables, class variables, and global variables?
    - - extra variables used for clarity when needed
      - references to variables close together
      - data types simple so that they minimize complexity
      - complicated data accessed through abstract access routines (abstract data types)
    - - nominal path through the code is clear
      - related statements grouped together
      - relatively independent groups of statements been packaged into their own routines
      - normal case follows the if rather than the else
      - control structures simple so that they minimize complexity
      - each loop perform one and only one function
      - nesting minimized
      - boolean expressions been simplified by using additional boolean variables, boolean functions, and decision tables
    - - program’s layout shows its logical structure
    - - straightforward, not clever, code
      - implementation details hidden as much as possible
      - program written in terms of the problem domain as much as possible
- - - - Nassi-Schneidermann Charts
      - State diagrams
      - UML interaction diagrams
      - Flowcharts
    - - Structure (call) charts
      - Data-Flow Diagrams
      - SADT (Structured Analysis and Design Technique)
      - E-R
      - UML class relationship diagrams
- - - - a (limited) language parser
        
        which does what
        
        extract info about module/function structure and function parameters
      - specially formatted blocks of comments embedded in the source code
        
        which does what
        
        encourages updating comments
        as you go
        
        makes code useful for application writers
        
        in 3 ways
        
        lessens need to access actual code
        
        Generate linked documents to facilitate browsing of referenced type names and other entities
        
        IDEs use this to help in live code editing sessions
    - - markup enclosed in /* ./
        
        contains two things
        
        normal comments
        
        special markup
        
        6 common ones
        
        author authorName
        
        version versionNumber
        
        param name description
        
        return description
        
        throws exceptionClassName description
        
        see crossReference
      - 3 ways to run
        
        command line
        
        javadoc -d destinationDir -sourcepath sourceCodeDir \
        
        -link http://docs.oracle.com/javase/7/docs/api/
        
        doxygen configFile
        
        eclipse
        
        project->generate javadoc
        
        Eclox plugin
        
        gradle/ant tasks/plugins
    - - is an
        
        API generator for C/C++, but also works with java
      - markup similar to javadoc
        
        uses markdown for internal formatting
      - output as HTML
      - can generate 2 things
        
        uml-like diagrams
        
        hyperlinked source code
      - 3 ways to run
- - - - which makes
        
        test reports
    - - which make
        
        dependency reports
      - ex:
        
        plugins{ id ' project report' }
        in gradle build.xml
- - - - including 6 things
        
        Project web sites
        
        ex
        
        GitHub Pages
        
        provides a web server for projects hosted on github
        
        ex:https://github.com/owner/project
        
        1 more item...
        
        accomplished by
        
        1 more item...
        
        Networked access to version control
        
        Release (download) support
        
        Communications (e.g., messaging, wikis, announcements)
        
        Bug reporting and tracking
        
        Project personnel management