From 4fe8b6a7db445160768859259cd7025c0aaf1a8d Mon Sep 17 00:00:00 2001 From: Robert Underwood Date: Tue, 17 Nov 2015 11:43:47 -0500 Subject: [PATCH 1/4] An initial proposal for coding standards. --- CONTRIBUTING.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 65 ------------------------------------------ 2 files changed, 76 insertions(+), 65 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6ade58f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Coding Standards + +## General Guidelines + +We largely follow the style guidelines found in the [Linux Kernel Coding +Style][Linux]. There are a few sections that do not specific apply to the +Hack Pack namely and can be ignored : 10 (Kconfigs), 13(Kernel Messages), +14(Memory Allocations in the Kernel), 17(Kernel Macros), and 19 (Inline +Assembly). + +Additionally, we have a few additional guidelines: + + +1. Code must compile under contest conditions: `g++ -g -O2 -std=gnu++0x -static $*` +2. Code must be delivered with the passing unit tests. +3. Code must be commented with detailed explanations and asymptotic notation + where applicable +4. Source code must solve a problem: It should solve a specific problem and + include all relevant IO and supporting code. The algorithm should not be in + a vacuum. +5. The condensed hackpack version should have the following removed: + + - Comments that are not _critical_ to the readers understanding + - All _library_ and `#include` code that can be found in other sections of the hackpack + - All input and output code that is not _critical_ to the readers + understanding + +## Writing Tests +All code must have tests that meet the following requirements + +1. All tests should be written using the [bats framework][bats], and use `tap` + compliant mode. See the `structures/set` section for an example. +2. Test at least the upper and lower boundaries of the allowed inputs. +3. Testing files should be postfixed by `-test` prior to the extension. For + example, `foo.cpp` test files should be called `foo-test.cpp` and + `foo-test.in` respectively +4. Tests should be runnable by calling `make test` in the directory of the source + + + The tests should return 0 in the case that all test cases passed + + The tests should return 2 in the case that any test cases failed + +## Folder Structure and File Naming conventions +All examples assume a topic called `foo` and a sample problem `bar`: + ++ All file names should be lowercase with `-` (hyphens) separating the words + in a file. For example, `ten-commandments.tex` instead of + `TenCommandments.tex` ++ All sample contest problems should be in a subdirectory called `problems` + and in a further subdirectory based on the problem name. For example if the + topic `foo` has a problem `bar` the path to the code sample could be `foo/problems/bar/bar.cpp`. ++ In the _rare_ circumstance that your finished product is one `tex` file, + place it in `general` instead ++ See how the `set` material is laid out for reference. It is in + `structures/set` + + ++ `foo` the name of the branch where `foo` is being worked on ++ `foo.tex` the hackpack documentation on the algorithm ++ `foo.cpp` reference code for the foo data structure in C++ if applicable ++ `bar.in` sample input for foo.cpp if applicable ++ `bar.out` sample output for foo.cpp if applicable ++ `bar.exe` untracked compiled binary __DO NOT ADD THIS__. It makes it + easier to spot in the `.gitignore`. ++ `bar.py` a version of `foo.cpp` in python if applicable. _Alternate + versions of algorithms in languages other than C++ should be written after + the C++ code is written_ ++ `bar.example` files such as `.vimrc` that do not have an extension normally ++ `bar.bats` Automated test case written in bats ++ `bar-test.cpp` An automated unit test written in cpp ++ `bar-test.in` Data for the automated unit test ++ `bar-test.out` Expected output for the automated unit test ++ In the case of multiple files of the same type, they should be postfixed a + number for example `bar-test1.out` or `bar-test1.in`. + +[Linux]: https://www.kernel.org/doc/Documentation/CodingStyle +[bats]: https://github.com/sstephenson/bats diff --git a/README.md b/README.md index 4b475a3..4fb8092 100644 --- a/README.md +++ b/README.md @@ -58,40 +58,6 @@ For all projects and improvements: If you have any questions related to the issues in the tracker, comment on the issues and mention one of the owners. -#### Folder Structure and File Naming conventions -All examples assume a topic called `foo` and a sample problem `bar`: - -+ All file names should be lowercase with `-` (hyphens) separating the words - in a file. For example, `ten-commandments.tex` instead of - `TenCommandments.tex` -+ All sample contest problems should be in a subdirectory called `problems` - and in a further subdirectory based on the problem name. For example if the - topic `foo` has a problem `bar` the path to the code sample could be `foo/problems/bar/bar.cpp`. -+ In the _rare_ circumstance that your finished product is one `tex` file, - place it in `general` instead -+ See how the `set` material is laid out for reference. It is in - `structures/set` - - -+ `foo` the name of the branch where `foo` is being worked on -+ `foo.tex` the hackpack documentation on the algorithm -+ `foo.cpp` reference code for the foo data structure in C++ if applicable -+ `bar.in` sample input for foo.cpp if applicable -+ `bar.out` sample output for foo.cpp if applicable -+ `bar.exe` untracked compiled binary __DO NOT ADD THIS__. It makes it - easier to spot in the `.gitignore`. -+ `bar.py` a version of `foo.cpp` in python if applicable. _Alternate - versions of algorithms in languages other than C++ should be written after - the C++ code is written_ -+ `bar.example` files such as `.vimrc` that do not have an extension normally -+ `bar.bats` Automated test case written in bats -+ `bar-test.cpp` An automated unit test written in cpp -+ `bar-test.in` Data for the automated unit test -+ `bar-test.out` Expected output for the automated unit test - - - - #### Writing Documentation Documentation should be written in `LaTeX`: @@ -115,37 +81,6 @@ For each item in the Hackpack, please include the following in clearly delineate lessons learned, but solutions should remain. * As much as possible, index tags should __NOT__ be removed. -#### Writing Code -Code Must meet the following standards: - -1. Code should be indented with tabs and not exceed 80 characters per line. -2. Code must compile under contest conditions: `g++ -g -O2 -std=gnu++0x -static $*` -3. Code must be delivered with the passing unit tests. -4. Code must be commented with detailed explanations and asymptotic notation - where applicable -5. Code must be concise but not at the expense of readability -6. Source code must solve a problem: It should solve a specific problem and - include all relevant IO and supporting code. The algorithm should not be in - a vacuum. -7. The condensed hackpack version should have the following removed: - - * Comments that are not _critical_ to the readers understanding - * All _library_ and `#include` code that can be found in other sections of the hackpack - * All input and output code that is not _critical_ to the readers - understanding - -#### Writing Tests -All code must have tests that meet the following requirements - -1. All tests should be written using the [bats framework](https://github.com/sstephenson/bats), and use `tap` compliant mode. See the `structures/set` section for an example. -2. Test at least the upper and lower boundaries of the allowed inputs. -3. Testing files should be postfixed by `-test` prior to the extension. For - example, `foo.cpp` test files should be called `foo-test.cpp` and - `foo-test.in` respectively -4. Tests should be runnable by calling `make test` in the directory of the source - - + The tests should return 0 in the case that all test cases passed - + The tests should return 2 in the case that any test cases failed #### Different Versions of the Hack Pack From 3c3a96f7690a8a28faa628154ce5acd58ceaa3a1 Mon Sep 17 00:00:00 2001 From: Robert Underwood Date: Tue, 17 Nov 2015 16:09:55 -0500 Subject: [PATCH 2/4] Improvements suggested by Austin - Move list of section of Linux Kernel Style Guide that do not apply to a unordered list. - Move to Hack Pack as the default spelling Hack Pack in the documentation. - A few grammar fixes. --- CONTRIBUTING.md | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ade58f..2a8ace5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,10 +3,14 @@ ## General Guidelines We largely follow the style guidelines found in the [Linux Kernel Coding -Style][Linux]. There are a few sections that do not specific apply to the -Hack Pack namely and can be ignored : 10 (Kconfigs), 13(Kernel Messages), -14(Memory Allocations in the Kernel), 17(Kernel Macros), and 19 (Inline -Assembly). +Style][Linux]. There are a few sections that do not specifically apply to the +Hack Pack and can be ignored : + +- 10 - Kconfigs +- 13 - Kernel Messages +- 14 - Memory Allocations in the Kernel +- 17 - Kernel Macros +- 19 - Inline Assembly Additionally, we have a few additional guidelines: @@ -18,15 +22,16 @@ Additionally, we have a few additional guidelines: 4. Source code must solve a problem: It should solve a specific problem and include all relevant IO and supporting code. The algorithm should not be in a vacuum. -5. The condensed hackpack version should have the following removed: +5. The condensed Hack Pack version should have the following removed: - Comments that are not _critical_ to the readers understanding - - All _library_ and `#include` code that can be found in other sections of the hackpack + - All _library_ and `#include` code that can be found in other sections of the Hack Pack - All input and output code that is not _critical_ to the readers understanding ## Writing Tests -All code must have tests that meet the following requirements + +All code must have tests that meet the following requirements: 1. All tests should be written using the [bats framework][bats], and use `tap` compliant mode. See the `structures/set` section for an example. @@ -40,11 +45,11 @@ All code must have tests that meet the following requirements + The tests should return 2 in the case that any test cases failed ## Folder Structure and File Naming conventions + All examples assume a topic called `foo` and a sample problem `bar`: + All file names should be lowercase with `-` (hyphens) separating the words - in a file. For example, `ten-commandments.tex` instead of - `TenCommandments.tex` + in a file. For example, `ten-commandments.tex` instead of `TenCommandments.tex` + All sample contest problems should be in a subdirectory called `problems` and in a further subdirectory based on the problem name. For example if the topic `foo` has a problem `bar` the path to the code sample could be `foo/problems/bar/bar.cpp`. @@ -53,23 +58,24 @@ All examples assume a topic called `foo` and a sample problem `bar`: + See how the `set` material is laid out for reference. It is in `structures/set` +### Detailed Example -+ `foo` the name of the branch where `foo` is being worked on -+ `foo.tex` the hackpack documentation on the algorithm -+ `foo.cpp` reference code for the foo data structure in C++ if applicable -+ `bar.in` sample input for foo.cpp if applicable -+ `bar.out` sample output for foo.cpp if applicable -+ `bar.exe` untracked compiled binary __DO NOT ADD THIS__. It makes it ++ `foo` The name of the branch where `foo` is being worked on ++ `foo.tex` The Hack Pack documentation on the algorithm ++ `foo.cpp` Reference code for the foo data structure in C++ if applicable ++ `bar.in` Sample input for foo.cpp if applicable ++ `bar.out` Sample output for foo.cpp if applicable ++ `bar.exe` Untracked compiled binary __DO NOT ADD THIS__. It makes it easier to spot in the `.gitignore`. -+ `bar.py` a version of `foo.cpp` in python if applicable. _Alternate ++ `bar.py` A version of `foo.cpp` in python if applicable. _Alternate versions of algorithms in languages other than C++ should be written after the C++ code is written_ -+ `bar.example` files such as `.vimrc` that do not have an extension normally ++ `bar.example` Files such as `.vimrc` that do not have an extension normally + `bar.bats` Automated test case written in bats + `bar-test.cpp` An automated unit test written in cpp + `bar-test.in` Data for the automated unit test + `bar-test.out` Expected output for the automated unit test -+ In the case of multiple files of the same type, they should be postfixed a ++ In the case of multiple files of the same type, they should be postfixed by a number for example `bar-test1.out` or `bar-test1.in`. [Linux]: https://www.kernel.org/doc/Documentation/CodingStyle From 89991695163c6bcc39b710328865f2908da36303 Mon Sep 17 00:00:00 2001 From: Robert Underwood Date: Sat, 21 Nov 2015 20:14:35 -0500 Subject: [PATCH 3/4] Added a quick start section --- CONTRIBUTING.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a8ace5..1c0af71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,76 @@ # Coding Standards -## General Guidelines +## Quick Start + +When coding for the hackpack, we use the following style: + +- Use tabs for indentation +- Try to keep lines to 80 characters +- Use K&R style braces +- names should be descriptive, but not _extreemly_ long +- use `snake_case` for everything except constants and filenames +- use `UPPER_CASE` for constants +- use `example-name.txt` for file names + +Further more in order for code to be accepted it must: + +- Be delivered with passing unit tests written in [bats][bats] +- Compile with `g++ -g -O2 -sstd=gnu++0x -static` + +In short, C++ should look like this: + +```c++ +#include +using namespace std; + +#define CONSTANT_VALUE 7 +typedef pair pii; + +int example_global; + +int main() +{ +int size; +cin >> size; + +int i = 0; +while (i < size) { + cin >> values[i]; + i++; +} + +pii tmp = min_max(values,size); + +cout << tmp.first << ", " << tmp.second << endl; + +} + +pii min_max(const int * values, unsigned int size) +{ +// Computes the min and max of an array in O(N) time +// Parameters: +// values - the array to search +// size - size of the array +// Returns: the make_pair(min,max) + +int min_value = values[0]; +int max_value = values[0]; + +for (int i = 0; i < size; i++) { + if (values[i] < min_value) + min_value = values[i]; + if (values[i] > max_value) + max_value = values[i]; +} + +return make_pair(min_value, max_value); +} +``` + + +## Detailed Guidelines + +### Code We largely follow the style guidelines found in the [Linux Kernel Coding Style][Linux]. There are a few sections that do not specifically apply to the @@ -29,7 +99,7 @@ Additionally, we have a few additional guidelines: - All input and output code that is not _critical_ to the readers understanding -## Writing Tests +### Writing Tests All code must have tests that meet the following requirements: @@ -44,7 +114,7 @@ All code must have tests that meet the following requirements: + The tests should return 0 in the case that all test cases passed + The tests should return 2 in the case that any test cases failed -## Folder Structure and File Naming conventions +### Folder Structure and File Naming conventions All examples assume a topic called `foo` and a sample problem `bar`: @@ -58,7 +128,7 @@ All examples assume a topic called `foo` and a sample problem `bar`: + See how the `set` material is laid out for reference. It is in `structures/set` -### Detailed Example +#### Detailed Example + `foo` The name of the branch where `foo` is being worked on + `foo.tex` The Hack Pack documentation on the algorithm From e8561978b9ca77132c4e53bbe4963a4d5ce393a6 Mon Sep 17 00:00:00 2001 From: Robert Underwood Date: Sat, 21 Nov 2015 20:17:36 -0500 Subject: [PATCH 4/4] Fixed some inconsistent formatting --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c0af71..e2207c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,10 +7,10 @@ When coding for the hackpack, we use the following style: - Use tabs for indentation - Try to keep lines to 80 characters - Use K&R style braces -- names should be descriptive, but not _extreemly_ long -- use `snake_case` for everything except constants and filenames -- use `UPPER_CASE` for constants -- use `example-name.txt` for file names +- Names should be descriptive, but not _extreemly_ long +- Use `snake_case` for everything except constants and filenames +- Use `UPPER_CASE` for constants +- Use `example-name.txt` for file names Further more in order for code to be accepted it must: