Skip to main content

Home/ SoftwareEngineering/ Group items tagged comment

Rss Feed Group items tagged

kuni katsuya

Preemptive commit comments | Arialdo Martini - 0 views

  • Tell me what the software does
    • kuni katsuya
       
      tell me how the software should *behave*, not how the behavior was *implemented* ie. describe the changes in this commit from the behavioral perspective rather than implementation details
  • What is the project behavior, in this snapshot?
  • What did the programmers, in order to produce this snapshot?
  • ...43 more annotations...
  • committing comments describing the
  • behavior of the software,
  • rather than the
  • implementation or a description of what we did
  • commits’ comments started to look like BDD’s methods name: a description of a behavior.
  • principles
  • Talk about the feature, not about yourself
  • Don’t refer to the past
  • I know it’s now
  • list of benefits
  • More focus while developing
  • Commit review is much easier
  • Less cognitive load
  • You learn commenting much more precisely
  • commit comment becomes a
  • declaration of intent
  • like a BDD method name
  • No more “Just a fix“, “Improvements” or “I made this, this, this and also this” comments.
    • kuni katsuya
       
      BDD/TDD or any methodology aside, these are the worst commit comments as they are as useless as empty commit comments
  • Each preemptive comment triggers a micro design session
  • A preemptive comment sets a micro goal
    • kuni katsuya
       
      which also aligns well with the 'micro goal' or incremental deliverables approaches of most agile methodologies 
  • helps to focus a goal to be reached
  • Without preemptive comments, I often went on coding, always asking myself: “Should I commit now? Have I reached a stable state which I could consider a good commit?“
  • define micro-goals through preemptive comments
  • macro-goal through the feature branch name
  • A preemptive comment creates a little timebox
    • kuni katsuya
       
      similar to the timeboxing strategy of a short sprints, for instance
  • Writing comments preemptively puts the agreement between the pair members to a test
    • kuni katsuya
       
      more relevant to methodologies using pair programming
  • commit history gains a very balanced granularity
  • feature branch becomes a collection of evolutionary commits each of which has usually a 1:1 binding with tests
  • very easy to find which commit introduced a bug, since each commit is related to a single new goal/feature
  • Preemptive commit comments
  • Rule #2: write what the software
  • I started taking a lot of care of the words I was using in comments, commits, test names and classes/variables/methods’ names
  • be supposed to do,
  • not what you did
  • should
  • Introducing BDD
  • began with the simple attempt to replace the world
  • “should“
  • “test”
  • with the world
  • Rule #1: write commit comments before coding
  • use the same criteria for my commits’ comments as well.
  • (not what you did)
kuni katsuya

3 ways to serialize Java Enums | Vineet Manohar's blog - 0 views

  • Mapping enum to database column using JPA/Hibernate You can use any of the 3 approaches discussed above. Map the enum to an integer column. The persistence implementation should automatically convert enum to ordinal() and back for you. Map the enum to a String column. The persistence implementation should automatically convert the enum value to String value via the name() function. Map the enum using a business value. You should mark the enum field as @Transient, and create another String field which you can map to a String column in your database table. Here’s an example code snippet. view plaincopy to clipboardprint?@Entity  public class Product {   @Column   private String colorValue;     @Transient   public Color getColor() {    return Color.fromValue(colorValue);   }     public void setColor(Color color) {    this.colorValue = color.toValue();   }  }  
  • Approach 3: Using a user defined business value – Recommended approach! This approach involves assigning a an explicit user defined value to each enum constant and defining a toValue() and fromValue() methods on the enum to do the serialization and deserialization.
  • public enum Color {   RED("RED"), GREEN("GREEN"), BLUE("BLUE"), UNKNOWN("UNKNOWN");     private final String value;     Color(String value) {     this.value = value;   }     public static Color fromValue(String value) {     if (value != null) {       for (Color color : values()) {         if (color.value.equals(value)) {           return color;         }       }     }       // you may return a default value     return getDefault();     // or throw an exception     // throw new IllegalArgumentException("Invalid color: " + value);   }     public String toValue() {     return value;   }     public static Color getDefault() {     return UNKNOWN;   }  }  public enum Color { RED("RED"), GREEN("GREEN"), BLUE("BLUE"), UNKNOWN("UNKNOWN"); private final String value; Color(String value) { this.value = value; } public static Color fromValue(String value) { if (value != null) { for (Color color : values()) { if (color.value.equals(value)) { return color; } } } // you may return a default value return getDefault(); // or throw an exception // throw new IllegalArgumentException("Invalid color: " + value); } public String toValue() { return value; } public static Color getDefault() { return UNKNOWN; } } This approach is better than approach 1 and approach 2 above. It neither depends on the order in which the enum constants are declared nor on the constant names.
kuni katsuya

MySQL :: MySQL 5.5 Reference Manual :: 13.1.17 CREATE TABLE Syntax - 0 views

kuni katsuya

Dependency injection discourages object-oriented programming? @ Blog of Adam Warski - 0 views

  • Dependency injection discourages object-oriented programming?
  • if you’re using DI, and you have an X entity, do you have an XService or XManager with lots of method where X is the first argument?
    • kuni katsuya
       
      evidence of the anti-pattern of procedural design in a java ee6 cdi application
  • previous way is more procedural
    • kuni katsuya
       
      ie. ProductService.ship(Product,Customer)
  • ...12 more annotations...
  • service/manager is a set of procedures you can run, where the execution takes a product and a customer as arguments
  • better
  • OO approach
  • not saying that achieving the above is not possible with a DI framework
  • only that DI
  • encourages the ProductService approach
    • kuni katsuya
       
      well, dependency injection, but moreover, the soa approach to service design tends to force otherwise intelligent software engineers into doing procedural design the services just end up being bags of method calls that implement any type of behavior, with the domain objects or entity beans being reduced to mere data structures with little responsibility or behavior beyond persistence. (which, in this anti-pattern, is typically mostly provided by the repository or dao class! ie. domain object crud)
  • it’s just easier
    • kuni katsuya
       
      ... if you just blindly follow the anti-pattern, of course  ;)
  • many benefits
    • kuni katsuya
       
      with the procedural approach, you also cannot implement polymorphic behavior, for instance
  • builder
  • fluent interface
  • it’s not for small projects
    • kuni katsuya
       
      fuckwhat? small or big matters not. if di is applied poorly, regardless of project size, it's an anti-pattern! disregard these comments!
  • problems with DI frameworks:
    • kuni katsuya
       
      not sure i agree with these points, but will refuse in a later sticky note
kuni katsuya

GraniteDS: Gas3 template for complex enums | Javalobby - 0 views

  • GraniteDS: Gas3 template for complex enums
  • changed enum.gsp from class:org/granite/generator/template/enum.gsp
  • I posted  a new version on github (master-branch) that
  • ...3 more annotations...
  • works with GraniteDS 3.0.0. 
  • https://github.com/graniteds/graniteds_builder 
  • fixed and committed to github
kuni katsuya

Chris Kelly: Programming Retrospective - 0 views

  • Programming Retrospective
  • anti-patterns
  • Final classes without interfaces
  • ...18 more annotations...
  • Lack of Defensive Programming
  • Exposure of super state to child classes
  • Printing out error messages to console instead of logging
  • Classes with unclear focus
  • Unwieldy or unneeded comments
  • Use of exceptions to control program flow
  • Throwing of ambiguous exceptions
  • Use parameter objects instead of long method signatures
  • Never Duplicate Code
  • copy and paste job
  • Return nulls from methods
  • Null Object pattern
  • onus is then on the callee to check the result is not null before using the result
  • client then doesn't have to check for nulls
  • empty map should be returned
  • instead of returning null, an
  • Refactoring: Improving the Design of Existing Code
  •  Working Effectively with Legacy Code
kuni katsuya

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

  • 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
       
      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
       
      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
       
      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
       
      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
       
      DO NOT DO THIS this is just bad design
  • "null returns xxx"
    • kuni katsuya
       
      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
       
      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

How do I migrate my application from AS5 or AS6 to AS7 - JBoss AS 7.0 - Project Documen... - 0 views

  • Configure changes for applications that use Hibernate and JPA
  • Update your Hibernate 3.x application to use Hibernate 4
  • Changes for Hibernate 3.3 applications
  • ...16 more annotations...
  • Changes for Hibernate 3.5 applications
  • if your application uses Hibernate 3 classes that are not available in Hibernate 4, for example, some of the validator or search classes, you may see ClassNotFoundExceptions when you deploy your application. If you encounter this problem, you can try one of two approaches: You may be able to resolve the issue by copying the specific Hibernate 3 JARs containing those classes into the application "/lib" directory or by adding them to the classpath using some other method. In some cases this may result in ClassCastExceptions or other class loading issues due to the mixed use of the Hibernate versions, so you will need to use the second approach. You need to tell the server to use only the Hibernate 3 libraries and you will need to add exclusions for the Hibernate 4 libraries. Details on how to do this are described here: JPA Reference Guide.
  • In previous versions of the application server, the JCA data source configuration was defined in a file with a suffix of *-ds.xml. This file was then deployed in the server's deploy directory. The JDBC driver was copied to the server lib/ directory or packaged in the application's WEB-INF/lib/ directory. In AS7, this has all changed. You will no longer package the JDBC driver with the application or in the server/lib directory. The *-ds.xml file is now obsolete and the datasource configuration information is now defined in the standalone/configuration/standalone.xml or in the domain/configuration/domain.xml file. A JDBC 4-compliant driver can be installed as a deployment or as a core module. A driver that is JDBC 4-compliant contains a META-INF/services/java.sql.Driver file that specifies the driver class name. A driver that is not JDBC 4-compliant requires additional steps, as noted below.
  • DataSource Configuration
  • domain mode, the configuration file is the domain/configuration/domain.xml
  • standalone mode, you will configure the datasource in the standalone/configuration/standalone.xml
  • MySQL datasource element:
  •         <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url>        <driver-class> com.mysql.jdbc.Driver </driver-class>        <driver> mysql-connector-java-5.1.15.jar </driver>
  •        <security>            <user-name> USERID </user-name>            <password> PASSWORD</password>        </security>
  • example of the driver element for driver that is not JDBC 4-compliant. The driver-class must be specified since it there is no META-INF/services/java.sql.Driver file that specifies the driver class name.
  •  <driver-class>com.mysql.jdbc.Driver</driver-class>
  • JDBC driver can be installed into the container in one of two ways: either as a deployment or as a core module
  • Install the JDBC driver
  • Install the JDBC driver as a deployment
  • In AS7 standalone mode, you simply copy the JDBC 4-compliant JAR into the AS7_HOME/standalone/deployments directory
  • example of a MySQL JDBC driver installed as a deployment:     AS7_HOME/standalone/deployments/mysql-connector-java-5.1.15.jar
kuni katsuya

equalsverifier - EqualsVerifier can be used in Java unit tests to verify whether the co... - 0 views

  • EqualsVerifierEqualsVerifier can be used in Java unit tests to verify whether the contract for the equals and hashCode methods in a class is met. The contracts are described in the Javadoc comments for the java.lang.Object class.
kuni katsuya

ListCollectionView/ArrayCollection tip for using GraniteDS - Ross Henderson - 0 views

  • The reason why GraniteDS generates properties of type ListCollectionView is simple : it internally uses collections implementations that extend ListCollectionView and not ArrayCollection. But as you have described when you manually assign collections, you should use ArrayCollection. It’s exactly the same as in Java when you do List list = new ArrayList().
  • ListCollectionView/ArrayCollection tip for using GraniteDS
  • new ListCollectionView();
  • ...4 more annotations...
  • instead of this:
  • do this:
  • new ArrayCollection();
  • I’m not really sure what the deal is
    • kuni katsuya
       
      see comment from william (wdrai) below (graniteds guy)
kuni katsuya

Plugins - Jenkins - Jenkins Wiki - 0 views

  • Git Plugin — This plugin allows use of Git as a build SCM
  • Subversion Plugin — This plugin adds the Subversion support (via SVNKit) to Jenkins
  • Subversion Release Manager — This plugin allows you to set up a job in Hudson for building specific revisions of a project.
  • ...77 more annotations...
  • Subversion Tagging Plugin — This plugin automatically performs subversion tagging (technically speaking svn copy) on successful build.
  • ViewVC Plugin — This plugin integrates ViewVC browser interface for CVS and Subversion with Hudson.
  • Source code management
  • Build Pipeline Plugin — This plugin creates a pipeline of Hudson\Jenkins jobs and gives a view so that you can visualise it.
  • Build tools
  • JBoss Management Plugin — This plugin allows to manage a JBoss Application Server during build procedure
  • Maven 2 Project Plugin — Jenkin's Maven 2 project type
  • Phing Plugin — This plugin allows you to use Phing to build PHP projects.
  • Post build task — This plugin allows the user to execute a shell/batch task depending on the build log output. Java regular expression are allowed.
  • Promoted Builds Plugin — This plugin allows you to distinguish good builds from bad builds by introducing the notion of 'promotion'.
  • Publish Over SSH Plugin — Publish files and/or execute commands over SSH (SCP using SFTP)
  • Selenium AES Plugin — This plugin is for continuous regression test by Selenium Auto Exec Server (AES).
  • Vagrant Plugin — This plugin allows booting of Vagrant virtual machines, provisioning them and also executing scripts inside of them
  • Unicorn Validation Plugin — This plugin uses W3C's Unified Validator, which helps improve the quality of Web pages by performing a variety of checks.
  • Build wrappers
  • Android Emulator Plugin — Lets you automatically generate, launch and interact with an Android emulator during a build, with the emulator logs being captured as artifacts.
  • Artifactory Plugin — This plugin allows deploying Maven 2, Maven 3, Ivy and Gradle artifacts and build info to the Artifactory artifacts manager.
  • AWS Cloudformation Plugin — A plugin that allows for the creation of cloud formation stacks before running the build and the deletion of them after the build is completed.
  • Build Keeper Plugin — Select a policy for automatically marking builds as "keep forever" to enable long term analysis trending when discarding old builds - or use to protect logs and artifacts from certain builds
  • Build Name Setter Plugin — This plugin sets the display name of a build to something other than #1, #2, #3, ...
  • SSH plugin — You can use the SSH Plugin to run shell commands on a remote machine via ssh.
  • SeleniumRC Plugin — This plugin allows you to create Selenium server instance for each project build.
  • Vagrant Plugin — This plugin allows booting of Vagrant virtual machines, provisioning them and also executing scripts inside of them
  • Timestamper — Adds timestamps to the Console Output.
  • VirtualBox Plugin — This plugin integrates Jenkins with VirtualBox (version 3, 4.0 and 4.1) virtual machine.
  • Version Number Plugin — This plugin creates a new version number and stores it in the environment variable whose name you specify in the configuration.
  • VMware plugin — This plugin allows you to start a VMware Virtual Machine before a build and stop it again after the build completes.
  • AWS Cloudformation Plugin — A plugin that allows for the creation of cloud formation stacks before running the build and the deletion of them after the build is completed.
  • Desktop Notifier for Jenkins — This is useful for those who are looking for a Desktop Notifier for Jenkins builds to automatically notify you about failed builds directly from their desktops.
  • Email-ext plugin — This plugin allows you to configure every aspect of email notifications. You can customize when an email is sent, who should receive it, and what the email says.
  • Google Calendar Plugin — This plugin publishes build records over to Google Calendar
  • HTML5 Notifier Plugin — Provides W3C Web Notifications support for builds.
  • Jabber Plugin — Integrates Jenkins with the Jabber/XMPP instant messaging protocol. Note that you also need to install the instant-messaging plugin.
  • Build reports
  • Checkstyle Plugin — This plugin generates the trend report for Checkstyle, an open source static code analysis program. 
  • Clover PHP Plugin — This plugin allows you to capture code coverage reports from PHPUnit. For more information on how to set up PHP projects with Jenkins have a look at the Template for Jenkins Jobs for PHP Projects.
  • Crap4J Plugin — This plugin reads the "crappy methods" report from Crap4J. Hudson will generate the trend report of crap percentage and provide detailed information about changes.
  • Dependency Analyzer Plugin — This plugin parses dependency:analyze goal from maven build logs and generates a dependency report
  • Dependency Graph View Plugin — Shows a dependency graph of the projects using graphviz. Requires a graphviz installation on the server.
  • FindBugs Plugin — This plugin generates the trend report for FindBugs, an open source program which uses static analysis to look for bugs in Java code. 
  • Grinder Plugin — This plugin reads output result files from Grinder performance tests, and will generate reports showing test results for every build and trend reports showing performance results across builds.
  • JSUnit plugin — This plugin allows you publish JSUnit test results
  • Performance Plugin — This plugin allows you to capture reports from JMeter and JUnit . Hudson will generate graphic charts with the trend report of performance and robustness.
  • PerfPublisher Plugin — This plugin generates global and trend reports for tests results analysis. Based on an open XML tests results format, the plugin parses the generated files and publish statistics, reports and analysis on the current health of the project.
  • PMD Plugin — This plugin generates the trend report for PMD, an open source static code analysis program. 
  • Sonar plugin — Quickly benefit from Sonar, an open-source dashboard based on many analysis tools like Checkstyle, PMD and Cobertura.
  • testng-plugin — This plugin allows you to publish TestNG results.
  • Violations — This plug-in generates reports static code violation detectors such as checkstyle, pmd, cpd, findbugs, codenarc, fxcop, stylecop and simian.
  • xUnit Plugin — This plugin makes it possible to publish the test results of an execution of a testing tool in Jenkins.
  • Artifact uploaders
  • ArtifactDeployer Plugin — This plugin makes it possible to copy artifacts to remote locations.
  • Artifactory Plugin — This plugin allows deploying Maven 2, Maven 3, Ivy and Gradle artifacts and build info to the Artifactory artifacts manager.
  • Confluence Publisher Plugin — This plugin allows you to publish build artifacts as attachments to an Atlassian Confluence wiki page.
  • Deploy Plugin — This plugin takes a war/ear file and deploys that to a running remote application server at the end of a build
  • FTP-Publisher Plugin — This plugin can be used to upload project artifacts and whole directories to an ftp server.
  • HTML Publisher Plugin
  • Publish Over FTP Plugin — Publish files over FTP
  • Publish Over SSH Plugin — Publish files and/or execute commands over SSH (SCP using SFTP)
  • S3 Plugin — Upload build artifacts to Amazon S3
  • SCP plugin — This plugin uploads build artifacts to repository sites using SCP (SSH) protocol.
  • Hudson Helper for Android — Monitor your CI builds right from your Android device.
  • Hudson Mobi, the iPhone, iPod and Android client for Hudson CI — The iPhone, iPod and iPad client for Hudson CI monitoring on the road.
  • Hudson Monitor for Android — Monitor and display the status of your builds on your Android™ phone.
  • External site/tool integrations
  • Jira Issue Updater Plugin — This is a Jenkins plugin which updates issues in Atlassian Jira (by changing their status and adding a comment) as part of a Jenkins job.
  • JIRA Plugin — This plugin integrates Atlassian JIRA to Jenkins.
  • ChuckNorris Plugin — Displays a picture of Chuck Norris (instead of Jenkins the butler) and a random Chuck Norris 'The Programmer' fact on each build page.
  • UI plugins
  • Active Directory plugin — With this plugin, you can configure Jenkins to authenticate the username and the password through Active Directory.
  • Audit Trail Plugin — Keep a log of who performed particular Jenkins operations, such as configuring jobs.
  • JClouds Plugin — This plugin uses JClouds to provide slave launching on most of the currently usable Cloud infrastructures.
  • Checkstyle Plugin — This plugin generates the trend report for Checkstyle, an open source static code analysis program. 
  • FindBugs Plugin — This plugin generates the trend report for FindBugs, an open source program which uses static analysis to look for bugs in Java code. 
  • JIRA Plugin — This plugin integrates Atlassian JIRA to Jenkins.
  • M2 Release Plugin — This plugin allows you to perform a release build using the maven-release-plugin from within Jenkins.
  • PMD Plugin — This plugin generates the trend report for PMD, an open source static code analysis program. 
  • Meme Generator Plugin — Generate Meme images when a build fails (and returns to stable), and post them on the project page.
1 - 12 of 12
Showing 20 items per page