From 0822e88e34ed9f0e6aa5b11ba03c916b8991c678 Mon Sep 17 00:00:00 2001 From: oscardssmith Date: Thu, 29 Jun 2017 16:41:24 -0400 Subject: [PATCH] Updated coding-style.rst with more info about using netbeans, and tips for people not using it Updated documentation.rst to move the better way of installing sphinx first. --- .../source/developers/coding-style.rst | 44 ++++++++++--------- .../source/developers/documentation.rst | 23 ++-------- 2 files changed, 27 insertions(+), 40 deletions(-) diff --git a/doc/sphinx-guides/source/developers/coding-style.rst b/doc/sphinx-guides/source/developers/coding-style.rst index 1a1cb6e33c1..98c2e3a7459 100755 --- a/doc/sphinx-guides/source/developers/coding-style.rst +++ b/doc/sphinx-guides/source/developers/coding-style.rst @@ -2,26 +2,38 @@ Coding Style ============ -Like all development teams, the `Dataverse developers at IQSS `_ have their habits and styles when it comes to writing code. Let's attempt to get on the same page. :) - -.. contents:: |toctitle| - :local: - Java ---- Formatting Code ~~~~~~~~~~~~~~~ -Tabs vs. Spaces -^^^^^^^^^^^^^^^ +NetBeans +^^^^^^^^ + +We highly recommend using Netbeans as a text editor. This makes it significantly easier to commit code that is well formatted and type safe. By default, NetBeans will warn you about some things, but if you want better warnings and code formatting, download this##################TODO ADD FILE######################### zip file, and import it to your nNtBeans settings by going to options, import, and selecting the file. These settings will cause NetBeans to automatically format code that you've worked on whenever you save, point out many common problems in code, and make sure that all indentation uses spaces. + +Alternatively, you can set the warnings yourself. To do so, go to tools-> options-> editor -> hints, and turn on the following + - Braces + - Error Fixes + - JDK Migration Support + - Probable Bugs + - Standard Javac Warnings + -Don't use tabs. Use spaces. +Not NetBeans +^^^^^^^^^^^^ -Format Code You Changed with Netbeans -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you are not going to use NetBeans, here are code style tips in order to be consistent with the rest of the project. +- Use 4 spaces for indentation (not tabs) +- Make sure your code is type safe. +- Make sure not to use raw classes +- Use diamond interface when applicable +- Use javadoc and comments to help explain what your code is doing +- Try to make your code look roughly like the following sample -As you probably gathered from the :doc:`dev-environment` section, IQSS has standardized on Netbeans. It is much appreciated when you format your code (but only the code you touched!) using the out-of-the-box Netbeans configuration. If you have created an entirely new Java class, you can just click Source -> Format. If you are adjusting code in an existing class, highlight the code you changed and then click Source -> Format. Keeping the "diff" in your pull requests small makes them easier to code review. +For an example code that follows our styleguide, see this +############TODO INSERT IMAGE################################ We would like to someday automate the detection and possibly correction of code that hasn't been formatted using our house style (the default Netbeans style). We've heard that https://maven.apache.org/plugins/maven-checkstyle-plugin/ can do this but we would be happy to see a pull request in this area, especially if it also hooks up to our builds at https://travis-ci.org/IQSS/dataverse . @@ -45,16 +57,6 @@ Avoid Hard-Coding Strings Special strings should be defined as public constants. For example, ``DatasetFieldConstant.java`` contains a field for "title" and it's used in many places in the code (try "Find Usages" in Netbeans). This is better than writing the string "title" in all those places. -Type Safety -~~~~~~~~~~~ - -If you just downloaded Netbeans and are using the out-of-the-box settings, you should be in pretty good shape. Unfortunately, the default configuration of Netbeans doesn't warn you about type-safety problems you may be inadvertently introducing into the code. To see these warnings, click Netbeans -> Preferences -> Editor -> Hints and check the following: - -- "Raw Types" under "Standard Javac Warnings" - -If you know of a way to easily share Netbeans configuration across a team, please get in touch. - - Bike Shedding ------------- diff --git a/doc/sphinx-guides/source/developers/documentation.rst b/doc/sphinx-guides/source/developers/documentation.rst index fcca7aa0558..58f75b4b762 100755 --- a/doc/sphinx-guides/source/developers/documentation.rst +++ b/doc/sphinx-guides/source/developers/documentation.rst @@ -19,32 +19,17 @@ If you find a typo or a small error in the documentation you can easily fix it u Other Changes (Sphinx) ---------------------- -The documentation for Dataverse was written using Sphinx (http://sphinx-doc.org/). -If you are interested in suggesting changes or updates we recommend that you create +The documentation for Dataverse was written using Sphinx (http://sphinx-doc.org/). +If you are interested in suggesting changes or updates we recommend that you create the html files using Sphinx locally and the submit a pull request through GitHub. Here are the instructions on how to proceed: Installing Sphinx ~~~~~~~~~~~~~~~~~ -On a Mac: - -Download the sphinx zip file from http://sphinx-doc.org/install.html - -Unzip it somewhere. In the unzipped directory, do the following as -root, (sudo -i): - -python setup.py build -python setup.py install - -Alternative option (Mac/Unix/Windows): - -Unless you already have it, install pip (https://pip.pypa.io/en/latest/installing.html) - run ``pip install sphinx`` in a terminal - - +If you don't have it, install pip (https://pip.pypa.io/en/latest/installing.html) This is all you need. You should now be able to build HTML/pdf documentation from git sources locally. Using Sphinx @@ -52,7 +37,7 @@ Using Sphinx First, you will need to make a fork of the dataverse repository in GitHub. Then, you will need to make a clone of your fork so you can manipulate the files outside GitHub. -To edit the existing documentation go to ~/dataverse/doc/sphinx-guides/source directory inside your clone. There, you will find the .rst files that correspond to the guides in the dataverse page (http://guides.dataverse.org/en/latest/user/index.html). Now, using your preferred text editor, open and edit these files, or create new .rst files and edit the others accordingly. +To edit the existing documentation go to ~/dataverse/doc/sphinx-guides/source directory inside your clone. There, you will find the .rst files that correspond to the guides in the dataverse page (http://guides.dataverse.org/en/latest/user/index.html). Now, using your preferred text editor, open and edit these files, or create new .rst files and edit the others accordingly. Once you are done, open a terminal and change directories to ~/dataverse/doc/sphinx-guides . Then, run the following commands: