Skip to main content

Home/ SoftwareEngineering/ Group items matching "guidelines" in title, tags, annotations or url

Group items matching
in title, tags, annotations or url

Sort By: Relevance | Date Filter: All | Bookmarks | Topics Simple Middle
kuni katsuya

UML 2 Class Diagram Guidelines - 0 views

www.agilemodeling.com/...classDiagram.htm

uml class diagram best practices

shared by kuni katsuya on 19 Dec 12 - Cached
  • UML 2 Class Diagram Guidelines
  • 1.        General Guidelines
  • 2.        Class Style Guidelines
  • ...49 more annotations...
  • Use Common Terminology for Names
  • Prefer Complete Singular Nouns for Class Names
  • Name Operations with a Strong Verb
  • Name Attributes With a Domain-Based Noun
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      don't just use the attribute's type with first character lower cased!!! argghhh!  (eg. instead of Node node, Node parent)
  • Do Not Model Scaffolding Code
  • Include an Ellipsis ( … ) At The End of Incomplete Lists
  • Develop Consistent Method Signatures
  • Avoid Stereotypes Implied By Language Naming Conventions
  • 3.        Interfaces
  • Name Interfaces According To Language Naming Conventions
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      I+ is NOT an acceptable naming convention!  this is a very dumb, thoughtless, pointless convention originated by microsoft
    • kuni katsuya
      kuni katsuya on 19 Dec 12
  • Do Not Model the Operations and Attributes of an Interface in Your Classes
  • Consider an Interface to Be a Contract
  • 4.        Relationship Guidelines
  • Model Relationships Horizontally
  • Depict Similar Relationships Involving A Common Class As A Tree
  • Always Indicate the Multiplicity
  • reduce clutter in the diagram
  • Avoid a Multiplicity of “*”
  • Replace Relationships By Indicating Attribute Types
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      if dependency relationships were drawn between every class and the types of it's attributes, the class diagram becomes cluttered very quickly this dependency is obvious if the type is indicated for each attribute
  • Do Not Model Every Single Dependency
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      generalization of #7 what you show/don't show depends on the main concepts  you're trying to convey in any specific diagram
  • Write Concise Association Names In Active Voice
  • Indicate Directionality To Clarify An Association Name
  • Name Unidirectional Associations In The Same Direction
  • Indicate Role Names When Multiple Associations Between Two Classes Exist
  • Indicate Role Names on Recursive Associations
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      eg. parent, child
  • Make Associations Bi-Directional Only When Collaboration Occurs In Both Directions
  • Question Multiplicities Involving Minimums And Maximums
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      this just leads to stupid programming practices like hard-coding array sizes, making code more brittle
  • 6.        Inheritance Guidelines
  • “is a”
  • “is like” relationships
  • Apply the Sentence Rule For Inheritance
  • Place Subclasses Below Superclasses
  • A Subclass Should Inherit Everything
    • kuni katsuya
      kuni katsuya on 19 Dec 12
       
      if a subclass sets an attribute to null, implements a method returning null or throwing a NotImplementedException, it really isn't a subclass, or the superclass needs to be decomposed
  • 7.        Aggregation and Composition Guidelines
  • object is made up of other objects
  • aggregation
  • “is part of” relationships
  • whole-part relationship between two objects
  • Composition
  • stronger form of aggregation where the whole and parts have
  • coincident lifetimes, and it is very common for the whole to manage the lifecycle of its parts
  • Apply the Sentence Rule for Aggregation
  • Depict the Whole to the Left of the Part
  • Don’t Worry About Getting the Diamonds Right
  • associations, aggregation, composition, dependencies, inheritance, and realizations
  • line on a UML class diagram
  • defines a cohesive set of behaviors
  • Indicate Visibility Only On Design Models
  • Design Class Diagrams Should Reflect Language Naming Conventions
kuni katsuya

Stephen Colebourne's blog: Javadoc coding standards - 0 views

blog.joda.org/...javadoc-coding-standards.html

java javadoc BestPractices documentation design communication

shared by kuni katsuya on 13 Dec 12 - No Cached
  • Javadoc coding standards
  • explain some of the rationale for some of my choices
  • this is more about the formatting of Javadoc, than the content of Javadoc
  • ...63 more annotations...
  • Each of the guidelines below consists of a short description of the rule and an explanation
  • Write Javadoc to be read as source code
  • Making Javadoc readable as source code
  • Public and protected
  • All public and protected methods should be fully defined with Javadoc
  • Package and private methods do not have to be, but may
  • benefit from it.
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      think of it as internal design documentation when you revisit this code 8 months from now: - based on nothing but your well-chosen ;) package/class/method/variable names, will you recall all of your current design intentions and rationale? likely not - when you hand-off this code to another software engineer, how easy will it be to mostly rtfm? will you have to waste time preparing design/implementation notes specifically for the hand-off? if this is the case because the code is unreadable and not self-guiding and there's not already at least high level design notes in a wiki, you're doing it wrong!
  • If a method is overridden in a subclass, Javadoc should only be present if it says something distinct to the original definition of the method
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      ie. don't just copy-paste the javadoc from the superclass. that's mindless and pointless monkey work
  • Use the standard style for the Javadoc comment
  • Do not use '**/' at the end of the Javadoc
  • Use simple HTML tags, not valid XHTML
  • XHTML adds many extra tags that make the Javadoc harder to read as source code
  • Use a single <p> tag between paragraphs
  • Place a single <p> tag on the blank line between paragraphs:
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      this at least makes the paragraph breaks wysiwygísh and somewhat easier to read
  • Use a single <li> tag for items in a list
  • place a single <li> tag at the start of the line and no closing tag
  • Define a punchy first sentence
  • it has the responsibility of summing up the method or class to readers scanning the class or package
  • the first sentence should be
  • clear and punchy, and generally short
  • use the third person form at the start
  • Avoid the second person form, such as "Get the foo"
  • Use "this" to refer to an instance of the class
  • When referring to an instance of the class being documented, use "this" to reference it.
  • Aim for short single line sentences
  • Wherever possible, make Javadoc sentences fit on a single line
  • favouring between 80 and 120 characters
  • Use @link and @code wisely
  • @link feature creates a visible hyperlink in generated Javadoc to the target
  • @code feature provides a section of fixed-width font, ideal for references to methods and class names
  • Only use @link on the first reference to a specific class or method
  • Use @code for subsequent references.
  • This avoids excessive hyperlinks cluttering up the Javadoc
  • Never use @link in the first sentence
  • Always use @code in the first sentence if necessary
  • Adding a hyperlink in that first sentence makes the higher level documentation more confusing
  • Do not use @code for null, true or false
  • Adding @code for every occurrence is a burden to both the reader and writer of the Javadoc and adds no real value.
  • Use @param, @return and @throws
  • @param entries should be specified in the same order as the parameters
  • @return should be after the @param entries
  • followed by @throws.
  • Use @param for generics
  • correct approach is an @param tag with the parameter name of <T> where T is the type parameter name.
  • Use one blank line before @param
  • This aids readability in source code.
  • Treat @param and @return as a phrase
  • They should start with a lower case letter, typically using the word "the". They should not end with a dot. This aids readability in source code and when generated.
  • treated as phrases rather than complete sentences
  • Treat @throws as an if clause
  • phrase describing the condition
  • Define null-handling for all parameters and return types
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      ideally, if the method in question has any specified/required pre and/or post conditions, they should be noted in the javadoc, not *just* null handling also, there are cleaner ways to design around this type of old school null handling hackage
  • methods should define their null-tolerance in the @param or @return
  • standard forms expressing this
  • "not null"
  • "may be null"
  • "null treated as xxx"
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      DO NOT DO THIS this is just bad design
  • "null returns xxx"
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      this might also stink of poor design ymmv
  • In general the behaviour of the passed in null should be defined
  • Specifications require implementation notes
  • Avoid @author
  • source control system is in a much better position to record authors
  • This wastes everyone's time and decreases the overall value of the documentation. When you have nothing useful to say, say nothing!
    • kuni katsuya
      kuni katsuya on 13 Dec 12
       
      likewise with javadoc on things like default constructors /**  * Creates an instance of SomeClass  */ public SomeClass() {} is equally useless and unnecessarily clutters up the source code
kuni katsuya

http://google-styleguide.googlecode.com/svn/trunk/xmlstyle.html - 0 views

google-styleguide.googlecode.com/...xmlstyle.html

xml style guide best practices

shared by kuni katsuya on 13 May 12 - Cached
  • This document provides a set of guidelines for general use when designing new XML document formats
kuni katsuya

Authentication Cheat Sheet - OWASP - 0 views

www.owasp.org/...Authentication_Cheat_Sheet

security authentication CheatSheet

shared by kuni katsuya on 09 Aug 12 - No Cached
  • Authentication Cheat Sheet
  • Sessions should be
  • unique per user
  • ...26 more annotations...
  • computationally very difficult to predict
  • "strong" password policy
  • Secure Password Recovery Mechanism
  • Require re-authentication for Sensitive Features
  • Authentication and Error Messages
  • can be used for the purposes of user ID and password enumeration
  • Incorrectly implemented error messages
  • generic manner
  • respond with a generic error message regardless if the user ID or password was incorrect
  • give no indication to the status of an existing account
  • Authentication responses
  • Invalid user ID or password"
  • does not indicate if the user ID or password is the incorrect parameter
  • Transmit Passwords Only Over TLS
  • login page
  • all subsequent authenticated pages
  • must be exclusively accessed over TLS
  • unencrypted session ID
  • credentials
  • Implement Account Lockout
  • lock out an account if more than a preset number of unsuccessful login attempts are made
  • can produce a result that locks out entire blocks of application users accounts
    • kuni katsuya
      kuni katsuya on 21 Sep 12
       
      somewhat of a denial-of-service attack, since legitimate users can no longer access their accounts/services
  • sensible strategy
  • is to lockout accounts for a number of hours
  • Password lockout mechanisms have a logical weakness
  • Session Management General Guidelines
1 - 7 of 7
Showing 20▼ items per page