in Education by
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. Closed 9 years ago. I have a colleague who insists that his code doesn't need comments, it's "self documenting." I've reviewed his code, and while it's clearer than code which I've seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code. Help me understand his point of view. What is self documenting code Can it really replace well commented and documented code Are there situations where it's better than well documented and commented code Are there examples where code cannot possibly be self-documenting without comments Maybe it's just my own limitations, but I don't see how it can be a good practice. This is not meant to be an argument - please don't bring up reasons why well commented and documented code is high priority - there are many resources showing this, but they aren't convincing to my peer. I believe I need to more fully understand his perspective to convince him otherwise. Start a new question if you must, but don't argue here. Also, those of you who are arguing against self documenting code -this is primarily to help me understand the perspective (ie, positive aspects) of self-documenting code evangelists. JavaScript questions and answers, JavaScript questions pdf, JavaScript question bank, JavaScript questions and answers pdf, mcq on JavaScript pdf, JavaScript questions and solutions, JavaScript mcq Test , Interview JavaScript questions, JavaScript Questions for Interview, JavaScript MCQ (Multiple Choice Questions)

1 Answer

0 votes
by
I think its a matter of the right amount of documentation, rather than all or none. If the parameters to a function are well named, you often don't have to say exactly what they are, e.g. char *CustomerName is pretty obvious. If you use assert value ranges for parameters, you don't have to document those ranges as well. IMO, documentation should cover everything which is less than obvious and hence needs some explanation, and most code needs some documentation. Personally, I'd rather see an illustrative example of how a given function works than descriptive documentation, in most cases. Documentation for documentations sake can be a waste of time, as the documentation needs maintenance to be kept up to date with the code base. If no one will benefit from reading it, don't produce it.

Related questions

0 votes
    What will be the output of the following Python code? class tester: def __init__(self, id): self.id = str(id) id="224" >>>temp ... >>>print(temp.id) a) 12 b) 224 c) None d) Error...
asked Jan 2, 2023 in Technology by JackTerrance
0 votes
    What will be the output of the following Python code? class tester: def __init__(self, id): self.id = str(id) id="224" >>>temp ... >>>print(temp.id) a) 12 b) 224 c) None d) Error...
asked Jan 2, 2023 in Technology by JackTerrance
0 votes
    A computer ________ is a malicious code which self-replicates by copying itself to other programs. (a) ... for-Cyber Security:,Cyber Security-Jobs:,Cyber Security Applications...
asked Nov 1, 2021 in Education by JackTerrance
0 votes
    Closed. This question is opinion-based. It is not currently accepting answers. Want to improve this question ... Questions for Interview, JavaScript MCQ (Multiple Choice Questions)...
asked Mar 12, 2022 in Education by JackTerrance
0 votes
    For barchart and _________ non-trivial methods exist for tables and arrays, documented at barchart.table. (a) ... of R Programming Select the correct answer from above options...
asked Feb 10, 2022 in Education by JackTerrance
0 votes
    ___________ are the most commonly documented object. (a) Interface (b) Class (c) Functions (d) Libraries This ... of R Programming Select the correct answer from above options...
asked Feb 10, 2022 in Education by JackTerrance
0 votes
    It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly ... Questions for Interview, JavaScript MCQ (Multiple Choice Questions)...
asked Mar 5, 2022 in Education by JackTerrance
0 votes
    It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly ... Questions for Interview, JavaScript MCQ (Multiple Choice Questions)...
asked Mar 5, 2022 in Education by JackTerrance
0 votes
    An urn contains 2 white and 2 black balls .A ball is drawn at random.If it is white ,it is not replace ... third ball drawn is black. Select the correct answer from above options...
asked Nov 13, 2021 in Education by JackTerrance
0 votes
    Shown below is the input NumPy array. Delete column two and replace it with the new column given below....
asked Apr 24, 2021 in Technology by JackTerrance
0 votes
    very quick newbish question here... In the jquery-mobile docs, it says that Note that the refresh() ... Questions for Interview, JavaScript MCQ (Multiple Choice Questions)...
asked Feb 21, 2022 in Education by JackTerrance
0 votes
    Is it advisable to replace the policy with another policy?...
asked Dec 31, 2020 in Health by Editorial Staff
0 votes
    Which Semantic element is best suitable for content like blog post that is self contained, independent and can be republished?...
asked Apr 10, 2021 in Education by JackTerrance
0 votes
    Can I become a self-taught data scientist? Select the correct answer from above options...
asked Jan 17, 2022 in Education by JackTerrance
...