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>

Solve

Solution Stats

44 Solutions
8 Solvers

Last Solution submitted on Jul 16, 2019

Last 200 Solutions

Solution Comments

Solution 1671361

2 Comments

2 Comments

David Verrelli on 24 Jun 2019

If you describe a problem as simple, William, you'll invite close inspection.... Maybe you'll find a benefit in commenting the code in your next submission.

William on 16 Jul 2019

Touche! Yes, the new examples make the more extensive comments worthwhile.

Solution 1423628

1 Comment

1 Comment

David Verrelli on 4 Feb 2018

Hello, margreet docter. Congratulations on solving the Problem. I hope you won't mind if I make a few observations. . . . (1) The function you have used on line 12 [the first line inside your loop] can also take two inputs. Have a look at the documentation for the function to see another syntax that would achieve the same thing. . . . (2) If you care about Cody "size", you could delete lines 14 & 19 in a resubmission, as they are only echoing values to the screen to assist in debugging. . . . (3) In this sort of problem, where a focus is on precision and decimal places, you might sometimes find it helpful to use the fprintf command to produce debugging output, with the syntax fprintf(formatSpec,A1,...,An), as this gives you more power to customise the format [e.g. scientific, or integer, or decimal; number of decimal places; etc.]. —DIV

Solution 1349348

1 Comment

1 Comment

David Verrelli on 3 Jul 2019

Nice one :-)

Problem Recent Solvers8

Problem Tags

basics comments

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 Solvers8

Suggested Problems

More from this Author31

Problem Tags

Community Treasure Hunt

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

Solution Stats

Last 200 Solutions

Solution Comments

Problem Recent Solvers8

Suggested Problems

More from this Author31

Problem Tags

Community Treasure Hunt

Players