Development Tutorial - The Diigo Meta page

• 23 Aug 08
  

  Tauruser Lin
  • project submission application
  • <property name="java_1_3_bootclasspath" value="C:\Program Files\JavaSoft\JRE\1.3.1_10\lib\rt.jar" />
  • <!-- 3rd Party Dependencies -->
     <!-- <property name="junit.jar" value="${ext_libdir}/junit.jar"/>
     -->
  • ${tcs_libdir}
  • buildlibs
  • it is good practice to include all the necessary libraries here.
  • topcoder_global.properties reference is at the beginning of your build.xm
  • will always override properties set in the build.xml.
  • you should consider the public API in the design document as canon
  • behavior of the public classes into a private helper class
  • public API
  • the general behavior

  10 more annotations...

• 20 Aug 08
  

  Eisenham Wong

  This is not to say that every design is flawless; quite the opposite. There is almost always room to improve any design. However, disagreements with design decisions are fixed by design revision, not by development. The implementation phase of the development process is not the appropriate time to remedy design issues, unless they are fatal to the project.

  • This is not to say that every design is flawless; quite the opposite. There is almost always room to improve any design. However, disagreements with design decisions are fixed by design revision, not by development. The implementation phase of the development process is not the appropriate time to remedy design issues, unless they are fatal to the project.

  • Contents

     

    /conf - This directory, if present, will contain configuration files for your component. Sometimes this will include configuration for components your submission will rely on, or sample configuration files written by the designer. If no such files were created during design phase, you may not have this directory in your distribution. If your component uses configuration files, you will need to create this directory on your own.

     

    /docs - This directory contains all current documentation for your component. This includes a .zargo or .zuml UML design specification, as well as the requirements and component specification. The design documents are covered in more detail in Section IV.

     

    /lib - Here you will find all required components level libraries that your component will require. Not included here are system level libraries (e.g. ODBC drivers, and other libraries that may required more complicated installation). All TCS components that your project relies on should be included here. If any are missing, you need to contact your Product Manager.

      

    /src - This directory will contain all your source, when you complete your project. In the distribution, normally only a directory skeleton will be created here. Developers are responsible for source file generation, covered in more detail in Section IV.

     

    /test_files - This directory contains all files used by your component during testing. This can include special or extreme configuration files, input and output samples, database schema, and anything else non-compilable your testing needs. The distribution will often contain some sample testing data that the designer has created.

     

    Java

     

    /META-INF - This directory is created by the jar packager, and can be ignored.

     

    /build.xml - This is a default, possibly unconfigured build script. Build scripts are covered in more detail in Section III.
  • All this being said, you are encouraged to make any possible improvements on the underlying implementation. If you can refactor the behavior of the public classes into a private helper class: go for it! If you can come up with a more efficient data gathering or manipulation algorithm than the one specified by the designer: wonderful! The only part of the design set in stone is the public API and the general behavior of the component from the user's perspective. Basically, you can't change the "what" of your project, but you do have some freedom to improve the "how."

  • Development Innovation

     

    Different designs allow for different degrees of development-phase innovation. This is partly a matter of the complexity of the design itself, and partly a matter of the designer’s approach. It is possible for a design to describe the component so completely that component coding is reduced to a translation of pseudo code from the Component Specification into the appropriate language for the component. It is also possible for the design to be restricted to definition of the public API, leaving the developer to provide all other implementation details. Most designs, however, fall somewhere in the middle.

     

    Implementation of method bodies is always an area in which developers have an opportunity to put their own twist on the development. With some designs it may also be reasonable or even necessary to add private or package-private methods, constructors, or even whole classes that are not specified explicitly in the design documents. If and when you make such additions you should take care to ensure that they are both necessary and appropriate because these parts of the submission are likely to attract extra scrutiny from the Development Review Board. Developer additions (like any other element of the component), should generally have the narrowest possible scope and the most restrictive access that are consistent with their intended usage. Be sure everywhere to use the most appropriate types of objects and primitives for the tasks at hand. 
  • Building Your Project 

    Once you have generated and cleaned your stubs, you should be able to build your component with the build script. To do so, you simply execute your build tool from the command line, with a target.

     

    Here are the common build targets for [N]Ant:

                             

    Target  Name	Description
    compile	This target will compile your project into a fully functional binary unit (assuming that your code is correct).
    compile_tests	This target will compile your tests. It depends on a successful compile.
    compile_targets	(Java Only) This target will compile your component against the 1.3 JRE you configured. Normally, you must build against this target, to pass screening. Section 2 of the Component Specification should detail whether or not you need to compile_targets.
    test	This target will execute your tests. It depends on a successful compile_tests. After test execution, the results can be found in the /log directory.
    clean	This target will clean the /build directory, removing all compiled code and intermediate files from the project.
    dev_submission	This target will create a packaged submission for you to upload via Project Submit and Review, when your project is complete.
  • You should not include any personally identifiable information in your submission. Anywhere you would use your TCS handle (for instance, in an @author tag), put TCSDEVELOPER. This helps keep review as impartial and objective as possible. After you win, you'll change your code to include your handle (during Final Fixes).

  • there are some basic requirements. 

     
    •  Every file must contain a TopCoder copyright notice. 
    •  All public API elements MUST be commented fully (parameters, return types, exceptions). NOTE: This includes Unit Tests. 
    •  Any overly complex or large block of code should contain some inline commenting to explain purpose and function. 
    •  Documentation must be professional in tone and quality.
  • • ALWAYS implement a tested version of the demonstration from the component specification. 
    •  ALWAYS provide a meaningful message in assert and fail calls. 
    •  ALWAYS document your test code as well as you document your component code. 
    •  Break up your tests into discrete TestCase classes. If one TestCase becomes unmanageable, don't hesitate to break it into two or more classes. 
    •  Break up your tests within those classes into the smallest functions possible; this way, it is clear which areas of the component are failing. You can then use the number of tests passing and failing as a completion metric, as well. 
    •  Reduce code duplication and increase robustness with setUp() and tearDown(). 
    •  Test every public function for as much valid and invalid input as time allows. 
    •  Test expected component processes: loading, processing data, and saving data, for instance. 
    •  Don't forget to clean up your environment! Unit tests should leave the system in the same state they found it in; there should be no persistent changes. This is checked during development review. 
    •  Test classes are normal classes in every respect, except that they have special significance to the testing framework. These classes can inherit from a class intermediate between themselves and the final test. They may contain methods other than test methods. They may have state. 
    •  Because they are in the same package or namespace as the component classes they test, the unit tests can access package-private and protected classes and their members. 
    •  Interfaces cannot be tested directly, but methods that accept interface arguments can be presented with alternative implementations. This technique has great potential for verifying that the component does the expected things with and to its interface-typed fields and method arguments, and that it reacts correctly to exceptions thrown by methods invoked on such arguments.

  • First, you should review your code. Make sure that your submission meets the review guidelines (Section IX) as fully as possible. Finding small issues now will save you points later in the review process. Make sure that your directory structure is appropriate as above.

     

    Secondly, make sure your code compiles. If you're writing a Java solution, make sure that the compile_targets build target compiles, if applicable.

     

    Finally, run the dev_submission build target. This will build a compressed archive of your files. Make sure to verify that all the files you've written are in the archive, and add any missing files as needed. Your submission should include a successful log from your unit tests, all the files in the conf/ tree, and all the files and directories you need in test_files/. If you have time, you can extract your dev submission to another directory and ensure that it builds cleanly.
  • • Write clean, clear, efficient code. Even though there is no review line item specifically for this, reviewers are nevertheless likely to react better to code that is easy for them to read and understand. With efficient code you get a potential performance advantage in stress and benchmark testing, as well as likely kudos (and a few extra points) from the reviewers. 
    •  Write a comprehensive unit testing suite. Inadequate tests can cost you dearly because there are several review line items pertaining to the unit test suite. Tests should cover all non-private methods thoroughly, and they should be well documented. Doing a good job on the tests can be a big win because the unit test suite is one of the areas that are more frequently neglected. 
    •  Provide excellent documentation. The class and method documentation is the developer’s responsibility, and few developers seem to give it the attention it deserves. Good documentation will be clear and comprehensive. Read and become familiar with Javadoc’s docs. Note, for instance, that more or less arbitrary HTML can be inserted into documentation comments; appropriate use of that feature can be very effective. Try to put yourself in another developer’s position and ask yourself what you might possibly want to know about the component – then put it in. Read and follow Sun or Microsoft's guide on writing comments for the respective language, and also their related documentation on how to write API specifications. 
    •  Fully satisfy all requirements and provide all required functionality. Perhaps this should go without saying, but it will hurt your chances if anything is left out. Watch out for special cases and unusual inputs. 
    •  Pay attention to any issues that the designer may have disregarded or overlooked – thread safety, for instance, or portability (even Java and .NET software can have portability issues). Where you have discretion within the design, give your submission desirable properties such as these. 
  • The implementation addresses the functionality as detailed in the component design documents.
  • The implementation correctly uses the technologies that are specific to the component.
  • The implementation properly implements required algorithms as defined in section 1.3 of the Component Specification.
  • All classes, methods and variables declarations are exactly as they are defined in the design documents (visibility, types, modifiers, names, exception list).
  • No additional public or protected entities are present in the design. - You may only add private entities to the component.Package private and protected variables are not allowed. Package private methods are allowed, as long as they fit naturally into the design. Package private classes are allowed also, if they are used to provide helper methods. Private variables, methods and inner classes are allowed. All added entities must follow the language naming conventions and must use proper English. Note that when there are multiple packages, helper classes may need to be public. In this case the restriction about adding public classes and methods is relaxed.
  • The implementation properly maps class relationships.
  • The object types defined in the implementation are the best choice for the intended usage.
  • There is no useless code.
  • There is no code redundancy.
  • The code is clear and efficient.
  • The thrown exceptions provide suitable error messages and cause (where appropriate).
  • All code, including test cases, follows the TopCoder coding conventions.
  • The implementation code contains detailed documentation for classes, methods, and variables, written in Javadoc / XML style as required by the Java / C# coding standards.
  • There are no errors and no warnings while generating the Javadoc / XML documentation.
  • Unit Test Cases thoroughly and correctly test all methods and constructors.
  • Unit Test cases contain an implementation or a demonstration of how the component will be used.
  • Where applicable, Unit Test Cases properly configure the test environment.
  • Where applicable, files used in Unit Test Cases exist in the /test_files directory.
  • Where applicable, Unit Test cases do not leave temporary files on the file system, open network or database connections, open files or streams after testing is complete.
  • The unit test code contains detailed documentation for classes, methods and variables.
  • Every single required fix must be addressed. Your component WILL NOT be completed until they are.

  29 more annotations...

Would you like to comment?

Join Diigo for a free account, or sign in if you are already a member.