Problem 44405. Back to basics: adding comments to your code

Created by David Verrelli

Solve Later

{"relationships":[{"relationshipType":"http://schemas.mathworks.com/matlab/code/2013/relationships/document","targetMode":"","relationshipId":"rId1","target":"/matlab/document.xml"},{"relationshipType":"http://schemas.mathworks.com/matlab/code/2013/relationships/output","targetMode":"","relationshipId":"rId2","target":"/matlab/output.xml"}],"parts":[{"partUri":"/matlab/document.xml","relationship":[],"contentType":"application/vnd.mathworks.matlab.code.document+xml","content":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<w:document xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"><w:body><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>One of the most useful skills a programmer can develop is the skill — or habit — of writing descriptive comments within/above the code that they work on.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>Top reasons for including comments in one's code:</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"2\"/></w:numPr></w:pPr><w:r><w:t>Helpful while you are initially developing the code.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"2\"/></w:numPr></w:pPr><w:r><w:t>Helpful if you are collaborating on the development, so others need to be able to use/amend/revise it.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"2\"/></w:numPr></w:pPr><w:r><w:t>Helpful if you need to revisit the code later on (could be months or years later), such as to extend it or amend it.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"2\"/></w:numPr></w:pPr><w:r><w:t>Helpful if someone else may work on the code in future, such as to extend it or amend it.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"2\"/></w:numPr></w:pPr><w:r><w:rPr><w:b/></w:rPr><w:t>Helpful on Cody for other players who can learn from inspecting your code.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>MATLAB provides</w:t></w:r><w:r><w:t> </w:t></w:r><w:r><w:rPr><w:i/></w:rPr><w:t>three</w:t></w:r><w:r><w:t> main methods of adding</w:t></w:r><w:r><w:t> </w:t></w:r><w:hyperlink w:docLocation=\"https://au.mathworks.com/help/matlab/matlab_prog/comments.html\"><w:r><w:t>comments</w:t></w:r></w:hyperlink><w:r><w:t> to your code:</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"1\"/></w:numPr></w:pPr><w:r><w:t>comments;</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"1\"/></w:numPr></w:pPr><w:r><w:t>comments also serving as 'code section' delimiters &amp; titles (these may be more appropriate in</w:t></w:r><w:r><w:t> </w:t></w:r><w:hyperlink w:docLocation=\"https://au.mathworks.com/help/matlab/scripts.html\"><w:r><w:t>scripts</w:t></w:r></w:hyperlink><w:r><w:t> than within</w:t></w:r><w:r><w:t> </w:t></w:r><w:hyperlink w:docLocation=\"https://au.mathworks.com/help/matlab/functions.html\"><w:r><w:t>functions</w:t></w:r></w:hyperlink><w:r><w:t>, but it is still possible to practice using them here);</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr><w:numId w:val=\"1\"/></w:numPr></w:pPr><w:r><w:t>block comments.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:rPr><w:i/></w:rPr><w:t>Note: some other features of MATLAB that are related to comments are illustrated at the top of the Test Suite, but are outside the present scope. Specifically, ellipsis (...) is deemed here a technique primarily for line continuation, not primarily for adding descriptions to the code.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:rPr><w:b/></w:rPr><w:t>Your PRIMARY task is to utilize</w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t> </w:t></w:r><w:r><w:rPr><w:b/><w:i/></w:rPr><w:t>all three</w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t> comment styles in your submission.</w:t></w:r><w:r><w:t> Your comments will have to be of 'meaningful' length (i.e. not so short as to have no clear meaning).</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>However, to make it slightly more interesting — and to have something specific to comment upon — as a</w:t></w:r><w:r><w:t> </w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t>SECONDARY task</w:t></w:r><w:r><w:t> you will also have to solve the equation</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:rPr><w:b/></w:rPr><w:t>√(x³ − 3/2) = A</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>for x (find x), in which A is a constant that will be provided as an input. \"√\" represents the square-root radical sign. Note that generally x will</w:t></w:r><w:r><w:t> </w:t></w:r><w:r><w:rPr><w:i/></w:rPr><w:t>not</w:t></w:r><w:r><w:t> be an integer.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>Moreover, your result should be returned</w:t></w:r><w:r><w:t> </w:t></w:r><w:r><w:rPr><w:i/></w:rPr><w:t>rounded</w:t></w:r><w:r><w:t> (in the usual way) to the</w:t></w:r><w:r><w:t> </w:t></w:r><w:r><w:rPr><w:i/></w:rPr><w:t>minimum</w:t></w:r><w:r><w:t> number of decimal places so that the left-hand side of the equation will be within the span defined by </w:t></w:r><w:r><w:t> </w:t></w:r><w:r><w:rPr><w:b/></w:rPr><w:t>A ± 0.0001</w:t></w:r><w:r><w:t>.</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>EXAMPLE</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"code\"/></w:pPr><w:r><w:t><![CDATA[A = 8\nx = 4.031]]></w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"text\"/></w:pPr><w:r><w:t>The exact value of x is more accurately approximated as 4.031008989457290. However, this is more than the minimum required precision. By setting x = 4.031, the left-hand side of the equation yields 7.999973, which is only 0.000027 less than the target value of A, and therefore acceptable. Note that more aggressive rounding of x to x = 4.03 would yield an unacceptably poor estimate for A, namely 7.996926 (an error of 0.003074). See also the table below:</w:t></w:r></w:p><w:p><w:pPr><w:pStyle w:val=\"code\"/></w:pPr><w:r><w:t><![CDATA[ x √(x³ − 3/2) A Error Error size\n 4.0310089895 8.00000000013 8 +1.3E-10 OK\n 4.031008990 8.00000000165 8 +1.7E-09 OK\n 4.03100899 8.00000000165 8 +1.7E-09 OK\n 4.0310090 8.00000003212 8 +3.2E-08 OK\n 4.031009 8.00000003212 8 +3.2E-08 OK\n 4.03101 8.00000307881 8 +3.1E-06 OK\n 4.0310 7.99997261189 8 -2.7E-05 OK\n 4.031 7.99997261189 8 -2.7E-05 OK <—— Most rounding yielding \"OK\"\n 4.03 7.99692609695 8 -3.1E-03 Too big\n 4.0 7.90569415042 8 -9.4E-02 Too big\n 4. 7.90569415042 8 -9.4E-02 Too big]]></w:t></w:r></w:p></w:body></w:document>"},{"partUri":"/matlab/output.xml","contentType":"text/xml","content":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\" ?><embeddedOutputs><metaData><evaluationState>manual</evaluationState><layoutState>code</layoutState><outputStatus>ready</outputStatus></metaData><outputArray type=\"array\"/><regionArray type=\"array\"/></embeddedOutputs>"}]}

One of the most useful skills a programmer can develop is the skill — or habit — of writing descriptive comments within/above the code that they work on.Top reasons for including comments in one's code:<ol><li>Helpful while you are initially developing the code.</li><li>Helpful if you are collaborating on the development, so others need to be able to use/amend/revise it.</li><li>Helpful if you need to revisit the code later on (could be months or years later), such as to extend it or amend it.</li><li>Helpful if someone else may work on the code in future, such as to extend it or amend it.</li><li>Helpful on Cody for other players who can learn from inspecting your code.</li></ol>MATLAB provides three main methods of adding <a href = "https://au.mathworks.com/help/matlab/matlab_prog/comments.html">comments</a> to your code:<ul><li>comments;</li><li>comments also serving as 'code section' delimiters & titles (these may be more appropriate in <a href = "https://au.mathworks.com/help/matlab/scripts.html">scripts</a> than within <a href = "https://au.mathworks.com/help/matlab/functions.html">functions</a>, but it is still possible to practice using them here);</li><li>block comments.</li></ul>Note: some other features of MATLAB that are related to comments are illustrated at the top of the Test Suite, but are outside the present scope. Specifically, ellipsis (...) is deemed here a technique primarily for line continuation, not primarily for adding descriptions to the code.Your PRIMARY task is to utilize all three comment styles in your submission. Your comments will have to be of 'meaningful' length (i.e. not so short as to have no clear meaning).However, to make it slightly more interesting — and to have something specific to comment upon — as a SECONDARY task you will also have to solve the equation√(x³ − 3/2) = Afor x (find x), in which A is a constant that will be provided as an input. "√" represents the square-root radical sign. Note that generally x will not be an integer.Moreover, your result should be returned rounded (in the usual way) to the minimum number of decimal places so that the left-hand side of the equation will be within the span defined by A ± 0.0001.EXAMPLE<pre class="language-matlab">A = 8
x = 4.031
</pre>The exact value of x is more accurately approximated as 4.031008989457290. However, this is more than the minimum required precision. 
By setting x = 4.031, the left-hand side of the equation yields 7.999973, which is only 0.000027 less than the target value of A, and therefore acceptable. 
Note that more aggressive rounding of x to x = 4.03 would yield an unacceptably poor estimate for A, namely 7.996926 (an error of 0.003074). See also the table below:<pre> x	 √(x³ − 3/2)	A 	Error 	Error size
 4.0310089895	8.00000000013	8	+1.3E-10	OK
 4.031008990 	8.00000000165	8	+1.7E-09	OK
 4.03100899 	8.00000000165	8	+1.7E-09	OK
 4.0310090 	8.00000003212	8	+3.2E-08	OK
 4.031009 	8.00000003212	8	+3.2E-08	OK
 4.03101 	8.00000307881	8	+3.1E-06	OK
 4.0310 	7.99997261189	8	-2.7E-05	OK
 4.031 	7.99997261189	8	-2.7E-05	OK	&lt;—— Most rounding yielding "OK"
 4.03 	7.99692609695	8	-3.1E-03	Too big
 4.0 	7.90569415042	8	-9.4E-02	Too big
 4. 	7.90569415042	8	-9.4E-02	Too big</pre>

One of the most useful skills a programmer can develop is the skill — or habit — of writing descriptive comments within/above the code that they work on.

Top reasons for including comments in one's code:

# Helpful while you are initially developing the code.
# Helpful if you are collaborating on the development, so others need to be able to use/amend/revise it.  
# Helpful if you need to revisit the code later on (could be months or years later), such as to extend it or amend it.  
# Helpful if someone else may work on the code in future, such as to extend it or amend it. 
# *Helpful on Cody for other players who can learn from inspecting your code.*

MATLAB provides _three_ main methods of adding <https://au.mathworks.com/help/matlab/matlab_prog/comments.html comments> to your code:

* comments;
* comments also serving as 'code section' delimiters & titles (these may be more appropriate in <https://au.mathworks.com/help/matlab/scripts.html scripts> than within <https://au.mathworks.com/help/matlab/functions.html functions>, but it is still possible to practice using them here);
* block comments.

_Note:  some other features of MATLAB that are related to comments are illustrated at the top of the Test Suite, but are outside the present scope. Specifically, ellipsis (...) is deemed here a technique primarily for line continuation, not primarily for adding descriptions to the code._
 
*Your PRIMARY task is to utilize _all three_ comment styles in your submission.*  Your comments will have to be of 'meaningful' length (i.e. not so short as to have no clear meaning).

However, to make it slightly more interesting — and to have something specific to comment upon — as a *SECONDARY task* you will also have to solve the equation

*√(x³ − 3/2) = A*

for x (find x), in which A is a constant that will be provided as an input.  "√" represents the square-root radical sign.  Note that generally x will _not_ be an integer.

Moreover, your result should be returned _rounded_ (in the usual way) to the _minimum_ number of decimal places so that the left-hand side of the equation will be within the span defined by  *A ± 0.0001*.

EXAMPLE

A = 8
  x = 4.031

The exact value of x is more accurately approximated as 4.031008989457290.  However, this is more than the minimum required precision.  
By setting x = 4.031, the left-hand side of the equation yields 7.999973, which is only 0.000027 less than the target value of A, and therefore acceptable.  
Note that more aggressive rounding of x to x = 4.03 would yield an unacceptably poor estimate for A, namely 7.996926 (an error of 0.003074).  See also the table below:

x	 √(x³ − 3/2)	A 	Error 	Error size
 4.0310089895	8.00000000013	8	+1.3E-10	OK
 4.031008990 	8.00000000165	8	+1.7E-09	OK
 4.03100899 	8.00000000165	8	+1.7E-09	OK
 4.0310090 	8.00000003212	8	+3.2E-08	OK
 4.031009 	8.00000003212	8	+3.2E-08	OK
 4.03101 	8.00000307881	8	+3.1E-06	OK
 4.0310 	7.99997261189	8	-2.7E-05	OK
 4.031 	7.99997261189	8	-2.7E-05	OK	<—— Most rounding yielding "OK"
 4.03 	7.99692609695	8	-3.1E-03	Too big
 4.0 	7.90569415042	8	-9.4E-02	Too big
 4. 	7.90569415042	8	-9.4E-02	Too big

Solve

Solution Stats

55 Solutions
10 Solvers

Last Solution submitted on May 16, 2023

Last 200 Solutions

Solution Comments

Show comments

Problem Recent Solvers10

Problem Tags

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!

Problem 44405. Back to basics: adding comments to your code

Solution Stats

Last 200 Solutions

Solution Comments

Problem Recent Solvers10

Suggested Problems

More from this Author32

Problem Tags

Community Treasure Hunt

Problem 44405. Back to basics: adding comments to your code

Solution Stats

Last 200 Solutions

Solution Comments

Problem Recent Solvers10

Suggested Problems

More from this Author32

Problem Tags

Community Treasure Hunt

Players