Skip to main content

Home/ SoftwareEngineering/ Group items tagged guide

Rss Feed Group items tagged

Filter: All | Bookmarks | Topics Simple Middle
kuni katsuya

What is SiteCatalyst? | Adobe Developer Connection - 0 views

developer.omniture.com/...c-what-is-sitecatalyst

Adobe Omniture SiteCatalyst documentation

shared by kuni katsuya on 23 Jan 13 - No Cached
  • What is SiteCatalyst?
  • What is SiteCatalyst?
  • What is SiteCatalyst?
  • ...4 more annotations...
  • software-as-a-service (SaaS) solution that
  • collects web site visitor's online analytics data like page views and visits
  • provides both a data processing and reporting platform.
  • SiteCatalyst User's Guide
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

BlazeDS Developer Guide - 0 views

livedocs.adobe.com/...help.html

graniteds flex java type conversion

shared by kuni katsuya on 01 Nov 12 - Cached
  • Serializing between ActionScript and Java
  • java.util.Date (formatted for Coordinated Universal Time (UTC))
  • java.util.Date, java.util.Calendar, java.sql.Timestamp, java.sql.Time, java.sql.Date
  • ...19 more annotations...
  • Object (generic)
  • java.util.Map
  • Array (dense)
  • java.util.List
  • List becomes ArrayList SortedSet becomes TreeSet Set becomes HashSet Collection becomes ArrayList
  • Array (sparse) java.util.Map java.util.Map
  • java.util.Map If a Map interface is specified, creates a new java.util.HashMap for java.util.Map and a new java.util.TreeMap for java.util.SortedMap.
  • BlazeDS passes an instance of java.util.ArrayList to parameters typed with the java.util.List interface and any other interface that extends java.util.Collection. Then these types are
  • sent back to the client as mx.collections.ArrayCollection instances
  • If you require normal ActionScript Arrays sent back to the client, you must set the legacy-collection element to true in the serialization section of a channel-definition's properties; for more information, see Configuring AMF serialization on a channel.
  • legacy-collection Default value is false. When true, instances of
  • java.util.Collection
  • are returned as
  • ActionScript Arrays
  • legacy-map Default value is false. When true, java.util.Map instances are serialized as an ECMA Array or associative array instead of an anonymous Object.
  • A typical reason to use custom serialization is to avoid passing all of the properties of either the client-side or server-side representation of an object across the network tier.
  • standard serialization scheme, all public properties are passed back and forth between the client and the server.
  • Explicitly mapping ActionScript and Java objects
  • Private properties, constants, static properties, and read-only properties, and so on, are not serialized
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

Spring to Java EE - A Migration Experience | OCPsoft - 0 views

ocpsoft.org/...tion-guide-cdi-jsf-jpa-jta-ejb

spring javaee migration

shared by kuni katsuya on 18 May 12 - No Cached
  • The biggest difference you’ll find is, “Java EE already does that for you.”
  • kuni katsuya on 18 May 12
     
    The biggest difference you'll find is, "Java EE already does that for you."
kuni katsuya

Feature Visibility [Enterprise Architect User Guide] - 0 views

www.sparxsystems.com/...setfeaturevisibility.html

enterprisearchitect feature visibility verbosity

shared by kuni katsuya on 29 Jun 12 - No Cached
  • enables you to set the visibility of attributes and operations
  • hide or show attributes and operations
  • visibility you set applies only to the current diagram, so a Class can appear in one diagram with all features displayed, and in another with features hidden
kuni katsuya

Check Visual Changes to Diagrams [Enterprise Architect User Guide] - 0 views

www.sparxsystems.com/..._visual_changes_to_diagra.html

enterprisearchitect diagram diff

shared by kuni katsuya on 29 Jun 12 - No Cached
  • Baseline Diagram Compare feature is a quick and easy way to visually compare a current diagram with an earlier version
  • Access    Any of the following: •Project Browser diagram context menu | Compare to Baseline | <select baseline>: Show Differences•Project Browser package context menu | Package Control | Manage Baselines: Show Differences | Selected diagram context menu | Open Visual Diagram Diff •Diagram context menu | Compare to Baseline: Show Differences, or•Select Package | Project | Baselines: Show Differences | Selected diagram context menu | Open Visual Diagram Diff
kuni katsuya

Import Binary Module [Enterprise Architect User Guide] - 0 views

www.sparxsystems.com/...importbinary.html

enterprisearchitect jdk import

shared by kuni katsuya on 08 Jul 12 - No Cached
  • Import Binary Module
  • To import a binary module, right-click on the target package in the Project Browser and select the Code Engineering | Import Binary Module context menu option
    • kuni katsuya
      kuni katsuya on 04 Sep 12
       
      note: the file dialog that opens after selecting 'import binary module' opens with filtering for .net binaries, so .jars won't be visible. change filter to .jar and happy happy
    • kuni katsuya
      kuni katsuya on 08 Jul 12
       
      eg. to import jdk classes, import C:\Program Files\Java\jdk1.7.0_05\jre\lib\rt.jar
  • ...2 more annotations...
  • Java Archive (.jar)
  • Do not import private members checkbox excludes private members from libraries from being imported into the model
« First ‹ Previous 41 - 60 of 75 Next ›
Showing 20▼ items per page