PR Best Practices

PR Best Practices

Source Code Comments

When you are creating a new class or a method, do not forget to add class/method comments according to the following structure.

Class comments

 /*
  * Proper comment on the class like what it does and 
  * if there are design level description
  * 
  * @author <Authorname>
  * @since 2016-03-29 
  */

Method comments

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

Adding images

* res/ -> drawable/ Bitmap files (.png, .9.png, .jpg, .gif) or XML files that are compiled into the following drawable resource subtypes:

                 -  Bitmap files
                 -  Nine-Patches (re-sizable bitmaps)
                 -  State lists
                 -  Shapes
                 -  Animation drawables
                 -  Other drawables 

* res/ -> mipmap/ Drawable files for different launcher icon densities. 

Commits

1. Use meaningful commit messages
2. Do not over commit. (Do not include multiple commits for a small change)
3. Do not add the merge commits to the PR
4. Usually use a single commit for a single issue, unless the issues are related or contain a significant code change.
5. There are certain kind of files you do not add to source control. If you already don't know about them, please do a quick search and find them and remove them from your commit.

// Manju added below @manjumegh, please reach out to her in case of any comment/changes. // Just extending to existing Best Practices. It would be single place to consolidate for all student developers:

1. Never add dead code in commit, please clean it before sending for review.
2. Each commit should be as small as possible, but no smaller.
3. The smallest a commit can be is a single cohesive idea: don't make commits so small that they are meaningless on their own.
4. There should be a one-to-one mapping between ideas and commits: each commit should build one idea, and each idea should be implemented by one commit.
5. Turn large commits into small commits by dividing large problems into smaller problems and solving the small problems one at a time.
6. All code change should be along with unit test. Having at least 80% branch coverage and line coverage. (Though, ideally target should be 90%)