Skip to main content

Home/ SoftwareEngineering/ Group items tagged self

Rss Feed Group items tagged

Filter: All | Bookmarks | Topics Simple Middle
kuni katsuya

Emulating "self types" using Java Generics to simplify fluent API implementation | Pass... - 0 views

passion.forco.de/...lify-fluent-api-implementation

Java generics FluentAPI DesignPatterns ApiDesign

shared by kuni katsuya on 27 Mar 13 - No Cached
  • Emulating "self types" using Java Generics to simplify fluent API implementation
  • this article shows how "self types" can be emulated in Java using Generics
  • The only thing wich differs is the return type, which is always the
  • ...16 more annotations...
  • class implementing the overridden isNotNull
  • necessary because otherwise it would not be possible to add methods to a call chain which are defined in the concrete assertion class, but not in the more generic superclass where isNotNull is implemented
  • <ELEMENT_TYPE>
  • ELEMENT_TYPE actual
  • ELEMENT_TYPE actual
  • GenericAssert<ELEMENT_TYPE>
  • SELF_TYPE
  • SELF_TYPE
  • SELF_TYPE self()
  • (SELF_TYPE) this
  • SELF_TYPE isNotNull()
  •  return self();
  • SELF_TYPE extends GenericAssert<SELF_TYPE, ELEMENT_TYPE>
  • only subclasses of GenericAssert are allowed as SELF_TYPE
  • sometimes called a
  • self-bounded generic
kuni katsuya

Unquiet Code | Using Generics To Build Fluent API's In Java - 0 views

www.unquietcode.com/...s-to-build-fluent-apis-in-java

Java generics FluentAPI DesignPatterns ApiDesign

shared by kuni katsuya on 27 Mar 13 - No Cached
  • Using Generics To Build Fluent API's In Java
  • extends BaseClass
  • super(ChildClass.class)
  • ...19 more annotations...
  • accomplish the same idea using generics
  • creates a bad sort of dependency where we need to update the base class every time we make a new derived class. Not good!
  • superclass requests information about the child, and the child provides it
  • (CHILD)
  • <CHILD extends BakedGood<CHILD>>
  • CHILD
  • (CHILD)
  • CHILD
  • abstract
  • extends BakedGood<Cake>
  • The type parameter is saying “the Child class must extend Base<Child>”, forcing the Child class to provide its own type to the type system
  • Now that we can return the derived class in our chained method calls we are free to alternately call methods from the base class and the derived class
  • All of the normal polymorphic abilities are retained (you can see that we’ve implemented the abstract bake() method required by BakedGood)
  • .bake()
  • .bake()
  • practical applications of fluent API’s can be found
  • this one
  • best article I was able to find on the topic was
  • here and here
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

Illegitimus Non Interruptus - Published Patterns - 0 views

sites.google.com/...illigitimus-non-interruptus

scrum agile anti-patterns

shared by kuni katsuya on 18 Oct 12 - No Cached
  • Illegitimus Non Interruptus
  • dilemma arising from the situation in which multiple individuals, acting independently and rationally consulting their own self-interest, will ultimately deplete a shared limited resource even when it is clear that it is not in anyone's long-term interest for this to happen
  • allot time for interrupts and
  • ...1 more annotation...
  • do not allow the time to be exceeded
1 - 5 of 5
Showing 20▼ items per page