Programming/Style - Revision history

Pysdlb: /* Source Code Templates */

2023-03-23T11:18:39Z

‎Source Code Templates

Pysdlb: /* Next Steps */

2022-11-16T11:40:15Z

‎Next Steps

Pysdlb: /* Next Steps */

2022-11-16T11:40:04Z

‎Next Steps

Pysdlb: /* Navigation */

2022-11-16T11:36:08Z

‎Navigation

Pysdlb at 15:32, 8 November 2022

2022-11-08T15:32:41Z

Pysdlb at 12:31, 2 November 2022

2022-11-02T12:31:16Z

Pysdlb at 13:09, 13 October 2022

2022-10-13T13:09:23Z

Pysdlb at 09:03, 24 May 2021

2021-05-24T09:03:20Z

Pysdlb at 14:48, 17 June 2019

2019-06-17T14:48:37Z

Pysdlb at 09:37, 29 March 2019

2019-03-29T09:37:32Z

@@ Line 96: / Line 96: @@
+#
 # VIPER - HPC
-# ICTD Department
+# IT Department
 # Hull University
+#

← Older revision		Revision as of 11:40, 16 November 2022
Line 351:		Line 351:
	* [https://www.software.ac.uk/ www.software.ac.uk]		* [https://www.software.ac.uk/ www.software.ac.uk]
	* [http://www.stack.nl/~dimitri/doxygen/ Doxygen tool]		* [http://www.stack.nl/~dimitri/doxygen/ Doxygen tool]
		+

@@ Line 351: / Line 351: @@
 * [https://www.software.ac.uk/ www.software.ac.uk]
 * [http://www.stack.nl/~dimitri/doxygen/ Doxygen tool]
 [[Main Page]]    /    [[FurtherTopics/FurtherTopics #Programming| Back to Further Topics]]

← Older revision		Revision as of 11:36, 16 November 2022
Line 352:		Line 352:
	* [http://www.stack.nl/~dimitri/doxygen/ Doxygen tool]		* [http://www.stack.nl/~dimitri/doxygen/ Doxygen tool]

−	~~==Navigation==~~	+	[[Main Page]] / [[FurtherTopics/FurtherTopics #Programming\| Back to Further Topics]]
−
−	* [[~~Main_Page\|Home]]~~
−	* [[Applications\|Application support]]
−	* [[Libraries\|Library support]]
−	* [[Programming\|Development support]] *
−	* [[General\|General]]

@@ Line 350: / Line 350: @@
 * [https://git-scm.com/ Git versioning tool]
 * [https://www.software.ac.uk/ www.software.ac.uk]
-* [http://www.stack.nl/~dimitri/doxygen/ doxygen tool]
+* [http://www.stack.nl/~dimitri/doxygen/ Doxygen tool]
 ==Navigation==

@@ Line 153: / Line 153: @@
-* The major version number always starts at 1, a number starting at 0 would indicated a '''pre-release''' and '''not production quality'''.*
+* The major version number always starts at 1, a number starting at 0 would be indicated a '''pre-release''' and '''not production quality'''.*
 * Version numbers allow people providing support to ascertain exactly which code a user is running.
 * For large projects which involve more than one source file, [[https://git-scm.com/ Git]] is recommended as the versioning tool.
@@ Line 243: / Line 243: @@
 * Subroutines that describe primitive actions (e.g. calculateMean() ).
 * Complex logic should be avoided.
-* Commenting of non-trivial areas.
+* Commenting on non-trivial areas.
 Complicated logic for achieving a simple thing should be kept to a minimum since the code might be modified by another programmer in the future.
@@ Line 340: / Line 340: @@
 * [2] - Fortran code example from https://www.tutorialspoint.com/fortran/index.htm
-== Further Information ==
+== Next Steps ==
 * [https://en.wikipedia.org/wiki/Comment_(computer_programming) https://en.wikipedia.org/wiki/Comment_(computer_programming)]

@@ Line 4: / Line 4: @@
 ===Introduction===
-Coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices, and methods for each aspect of a program written in that language.
+Coding conventions are a set of guidelines for a specific programming language that recommend programming styles, practices, and methods for each aspect of a program written in that language.
 ===Purpose===
@@ Line 22: / Line 22: @@
 As with all types of design, there are several phases of production from inception to production (and then maintenance through software updates).
-Common methodologies include waterfall, prototyping, iterative and incremental development, spiral development, agile software development, rapid application  development, and extreme programming. Agile is the preferred style within the Viper team see the [[https://en.wikipedia.org/wiki/Agile_software_development Agile wikipedia]].
+Standard methodologies include waterfall, prototyping, iterative and incremental development, spiral development, agile software development, rapid application development, and extreme programming. Agile is the preferred style within the Viper team see the [[https://en.wikipedia.org/wiki/Agile_software_development Agile wikipedia]].
 * The default software repository method is [https://github.com GitHub] or [https://gitlab.com GitLab] (''essentially the same''). Using this is described here; [[Programming/GitHub|using GitHub]].
@@ Line 52: / Line 52: @@
 You should indent your code. However, it's also worth noting that it is a good idea to keep your indentation style consistent.
-This is only a matter of preference. There is no "best" style that everyone should be following. Actually, the best style is a consistent style. If you are part of a team or if you are contributing code to a project, you should follow the existing style that is being used in that project.
+This is only a matter of preference. There is no "best" style that everyone should follow. Actually, the best style is a consistent style. If you are part of a team or if you are contributing code to a project, you should follow the existing style that is being used in that project.
 The indentation styles are not always completely distinct from one another. Sometimes, they mix different rules. For example, in PEAR Coding Standards, the opening bracket "{" goes on the same line as control structures, but they go to the next line after function definitions.
@@ Line 160: / Line 160: @@
 ===Indentation===
-Indenting code allows us to see structure within code blocks and gives an obvious pattern to the structure, an example is shown below:
+Indenting code allows us to see the structure within code blocks and gives an obvious pattern to the structure, an example is shown below:
 <pre style="background-color: #f5f5dc; color: black; font-family: monospace, sans-serif;">
@@ Line 188: / Line 188: @@
 The comments should also be not complicated. The purpose of commenting is to help the person presently reading the source code.
-* Avoid obvious comments - commenting on your code is essential in terms of maintainability; however, it can be overdone or just be plain redundant.
+* Avoid obvious comments - commenting on your code is essential in terms of maintainability; however, it can be overdone or just plain redundant.
 * Code grouping - more often than not, certain tasks require a few lines of code. It is a good idea to keep these tasks within separate blocks of code, with some spaces between them.
 * Keep comments short and simple.
@@ Line 198: / Line 198: @@
 * Reference software tickets from our internal system and any others from suppliers as well.
-* The top of any program file -  This is called the "Header Comment". It should include all the defining information about who wrote the code, and why, and when, and what it should do.
+* The top of any program file -  This is called the "Header Comment". It should include all the defining information about who wrote the code, why, when, and what it should do.
 * Above every function. -   This is called the function header and provides information about the purpose of this "sub-component" of the program.
 * Inline - within the code where a description is necessary and non-trivial.
-* According to the Ada coding standard (2005), "Programmers should include comment whenever it is difficult to understand the code without the comments"
+* According to the Ada coding standard (2005), "Programmers should include comments whenever it is difficult to understand the code without the comments"
 <strong>Where to Not Comment</strong>:
@@ Line 231: / Line 231: @@
 There are two popular options with more descriptive (and therefore longer variable names):
-* '''camelCase''': First letter of each word is capitalized, except the first word.
+* '''camelCase''': The first letter of each word is capitalized, except the first word.
 * '''under_scores''': Underscores between words, like: ''pgsql_connect_dbase()''.
@@ Line 253: / Line 253: @@
 * Try and generate tests that will cover the maximum coverage of your code, particularly at the module level.
-Special areas of interest of error catching are the following:
+Special areas of interest in error catching are the following:
-* User Input which don't correspond to expected types or values.
+* User Input which doesn't correspond to expected types or values.
 * Data files where the data is out of expected values.
 * Out of bound arrays, some languages will not detect this automatically and completely fail.
@@ Line 264: / Line 264: @@
 * Use a common '''errorTrap''' subroutine to capture errors from a number of different program error events.
-Not putting checks where it would be unnecessary and slows down the execution particularly in ''HPC'' where speed is a high priority.
+Not putting checks where it would be unnecessary slows down the execution, particularly in ''HPC'' where speed is a high priority.
 For example ''[Reference 2]'':
@@ Line 279: / Line 279: @@
 </pre>
-'''Note''' : In this example x can never go negative anyway, why are we testing for it?
+'''Note''': In this example x can never go negative anyway, why are we testing for it?
@@ Line 286: / Line 286: @@
 The software should be capable of being compiled or interpreted on a number of different systems, not just Viper's architecture. If this cannot be achieved (i.e. some reliance on a certain architecture) then the program should be configurable to allow different systems to be used easily.
-Any example is shown below:
+An example is shown below:
 <pre style="background-color: #f5f5dc; color: black; font-family: monospace, sans-serif;">
@@ Line 310: / Line 310: @@
 ===Debugging===
-Programmers tend to write the complete code and then begin debugging and checking for errors. Though this approach can save time in smaller projects, bigger and complex ones tend to have too many variables and functions that need attention. Therefore, it is good to debug every module once you are done and not the entire program. This saves time in the long run so that one does not end up wasting a lot of time on figuring out what is wrong. Unit tests for individual modules, and/or functional tests for services and applications, can help with this.
+Programmers tend to write the complete code and then begin debugging and checking for errors. Though this approach can save time in smaller projects, bigger and more complex ones tend to have too many variables and functions that need attention. Therefore, it is good to debug every module once you are done and not the entire program. This saves time in the long run so that one does not end up wasting a lot of time on figuring out what is wrong. Unit tests for individual modules, and/or functional tests for services and applications, can help with this.
 In the absence of profilers, print statements can be useful although using ''logging'' or ''sys.stdout'' (Python) are a better approach. These can be enabled with a DEBUG flag, so preventing orphaned '''print''' statements within your program and also allowing this to be used during maintenance.
@@ Line 321: / Line 321: @@
 ===Documentation===
-A very useful tool here is [http://www.stack.nl/~dimitri/doxygen/ Doxygen] which can created html/latex based documentation. It relies on code commenting to work fully and so the earlier point on this is very important here. Another possible choice is FORD.
+A very useful tool here is [http://www.stack.nl/~dimitri/doxygen/ Doxygen] which can create HTML/latex-based documentation. It relies on code commenting to work fully and so the earlier point on this is very important here. Another possible choice is FORD.
 ===Deployment===
@@ Line 331: / Line 331: @@
 * Do not develop code that you can't maintain -  or anyone else can maintain either.
 * Do not make your software difficult to build and install - this comes back to maintainability again.
-* Do not keep the source code to yourself - [https://github.com/ GitHub] as an excellent de facto software versioning system.
+* Do not keep the source code to yourself - [https://github.com/ GitHub] is an excellent de facto software versioning system.
 * Do not forget documentation -  You know how it works, make this knowledge known to others who see your software for the first time.
 * Do not overlook testing.

@@ Line 20: / Line 20: @@
 ===Life Cycle===
-As with all types of design there are several phases of production from inception to production (and then maintenance through software updates).
+As with all types of design, there are several phases of production from inception to production (and then maintenance through software updates).
-Common methodologies include waterfall, prototyping, iterative and incremental development, spiral development, agile software development, rapid application
+Common methodologies include waterfall, prototyping, iterative and incremental development, spiral development, agile software development, rapid application  development, and extreme programming. Agile is the preferred style within the Viper team see the [[https://en.wikipedia.org/wiki/Agile_software_development Agile wikipedia]].
 * The default software repository method is [https://github.com GitHub] or [https://gitlab.com GitLab] (''essentially the same''). Using this is described here; [[Programming/GitHub|using GitHub]].
@@ Line 39: / Line 38: @@
 Easily the most important stage within the full life cycle and decisions made at this stage will have ramifications for the whole software. The main purpose of design is to fill in the details within the architectural design.
-Design requires a good conceptual model of the specification requirement. Without a good model we have the possibility of missing the goal of the software and also include the possibility to vastly increasing the time taken to project fruition.
+Design requires a good conceptual model of the specification requirement. Without a good model, we have the possibility of missing the goal of the software and also include the possibility of vastly increasing the time taken to project fruition.
 ===Programming Language Choice===
-Viper provides a large amount of different programming languages and can be extended to include software not included within this WIKI.
+Viper provides a large number of different programming languages and can be extended to include software not included within this WIKI.
-The usually rule here is to use the best programming language suitable for solving the task required of it.
+The usual rule here is to use the best programming language suitable for solving the task required of it.
 ==Coding Standards==
@@ Line 53: / Line 52: @@
 You should indent your code. However, it's also worth noting that it is a good idea to keep your indentation style consistent.
-This is only a matter of preference. There is no "best" style that everyone should be following. Actually, the best style, is a consistent style. If you are part of a team or if you are contributing code to a project, you should follow the existing style that is being used in that project.
+This is only a matter of preference. There is no "best" style that everyone should be following. Actually, the best style is a consistent style. If you are part of a team or if you are contributing code to a project, you should follow the existing style that is being used in that project.
 The indentation styles are not always completely distinct from one another. Sometimes, they mix different rules. For example, in PEAR Coding Standards, the opening bracket "{" goes on the same line as control structures, but they go to the next line after function definitions.
-Here is an example of some research code which works and compiles, but is very hard to read, to modify, to scale for anyone else. ''Reference [1]''.
+Here is an example of some research code that works and compiles, but is very hard to read, modify, to scale for anyone else. ''Reference [1]''.
 <pre style="background-color: #f5f5dc; color: black; font-family: monospace, sans-serif;">
@@ Line 85: / Line 84: @@
 </pre>
-'''Rationale'' : This is why a set of '''programming style''' recommendations like these are essential and significantly cut down the time spent on software and maintenance.
+'''Rationale'': This is why a set of '''programming style''' recommendations like these are essential and significantly cut down the time spent on software and maintenance.
 ===Source Code Templates===
@@ Line 151: / Line 150: @@
 * '''Major version numbers''' change whenever there is some significant change being introduced.
 * '''Minor version numbers''' change when a new, minor feature is introduced or when a set of smaller features is rolled out.
-* '''Patch numbers change''' when a new build of the software. This is normally for small bug-fixes or the like.
+* '''Patch numbers change''' when a new build of the software. This is normally for small bug fixes or the like.
@@ Line 185: / Line 184: @@
 ===Commenting===
-Commenting code is essential not only to the original author, but to maintainers of that code too and should clearly demonstrate the function of the code.
+Commenting code is essential not only to the original author but to maintainers of that code too and should clearly demonstrate the function of the code.
 The comments should also be not complicated. The purpose of commenting is to help the person presently reading the source code.
-* Avoid obvious comments - commenting your code is essential in terms of maintainability; however, it can be overdone or just be plain redundant.
+* Avoid obvious comments - commenting on your code is essential in terms of maintainability; however, it can be overdone or just be plain redundant.
 * Code grouping - more often than not, certain tasks require a few lines of code. It is a good idea to keep these tasks within separate blocks of code, with some spaces between them.
 * Keep comments short and simple.
@@ Line 201: / Line 200: @@
 * The top of any program file -  This is called the "Header Comment". It should include all the defining information about who wrote the code, and why, and when, and what it should do.
 * Above every function. -   This is called the function header and provides information about the purpose of this "sub-component" of the program.
-* In line - within the code where a description is necessary and non-trivial.
+* Inline - within the code where a description is necessary and non-trivial.
 * According to the Ada coding standard (2005), "Programmers should include comment whenever it is difficult to understand the code without the comments"
@@ Line 254: / Line 253: @@
 * Try and generate tests that will cover the maximum coverage of your code, particularly at the module level.
-Special areas of interesting of error catching are the following:
+Special areas of interest of error catching are the following:
 * User Input which don't correspond to expected types or values.
@@ Line 285: / Line 284: @@
 ===Portability===
-The software should be capable of being compiled or interpreted on a number of different systems, not just Viper's architecture. If this cannot be achieved (i.e. some reliance of a certain architecture) then the program should be configurable to allow different systems to be used easily.
+The software should be capable of being compiled or interpreted on a number of different systems, not just Viper's architecture. If this cannot be achieved (i.e. some reliance on a certain architecture) then the program should be configurable to allow different systems to be used easily.
 Any example is shown below:
@@ Line 322: / Line 321: @@
 ===Documentation===
-A very useful tool here is [http://www.stack.nl/~dimitri/doxygen/ Doxygen] which can created html/latex based documentation. It relies on code commenting to work fully and so the earlier point on this is very important here. Other possible choices are FORD.
+A very useful tool here is [http://www.stack.nl/~dimitri/doxygen/ Doxygen] which can created html/latex based documentation. It relies on code commenting to work fully and so the earlier point on this is very important here. Another possible choice is FORD.
 ===Deployment===

@@ Line 353: / Line 353: @@
 * [http://www.stack.nl/~dimitri/doxygen/ doxygen tool]
 * [[Main_Page|Home]]
 * [[Applications|Application support]]
 * [[General|General]]

@@ Line 25: / Line 25: @@
 development, and extreme programming. Agile is the preferred style within the Viper team see the [[https://en.wikipedia.org/wiki/Agile_software_development Agile wikipedia]].
-* The default software repository method is [https://github.com GitHub] or [https://gitlab.com GitLab (essentially the same). Using this is described here; [[Programming/GitHub|using GitHub]].
+* The default software repository method is [https://github.com GitHub] or [https://gitlab.com GitLab] (''essentially the same''). Using this is described here; [[Programming/GitHub|using GitHub]].
 ===Requirements===