Documentation of Server File Source Code

[jatin56]

I Have Documented the code present in Server.py file. I tried to maintain a proper standard while documentation. The documentation of code is done with my understanding of code and may require improvements or #132

[jatin56]

Can you Tell me the reason For avoiding Comments,It would help me to improve from next time

[jatin56]

I have used Natural Docs instead of sphinx for creating Documentation from Code. Created Documentation is present inside Docs Folder.

[theSage21]

Can you Tell me the reason For avoiding Comments,It would help me to improve from next time

The way I see it, programming is the act of communicating ideas to other people because if it was about communicating with the machine we were doing fine with assembly. So what are we communicating with when we write code?

1. you've got the grammar of whatever language you are using

2. names of functions/variables/classes

3. the layout of the code

4. x < 10? x+= 1: x += 2 and x += 1 if x < 10 else 2 do the same thing but the grammar of python makes the second one more readable and easily understood.

5. This line in our project is an example of improper naming. That is not a test. The test is actually inside test[0]. Comments also form a part of this category.

6. The last is the layout of the code. We are using black for that part. For example this code

    def __init__(self, *, use_dns_cache: bool=True, ttl_dns_cache: int=10, family: int=0, ssl: Union[None, bool, Fingerprint, SSLContext]=None, local_addr: Optional[Tuple[str, int]]=None, resolver: Optional[AbstractResolver]=None, keepalive_timeout: Union[None, float, object]=sentinel, force_close: bool=False, limit: int=100, limit_per_host: int=0, enable_cleanup_closed: bool=False, loop: Optional[asyncio.AbstractEventLoop]=None):

is better written as aiohttp has done it since it's obviously clear where and what the arguments to the function are.

Now that we understand that code is for communicating ideas to people, let's get to what comments are to be used for IMHO.

• clean code explains itself. It is obvious "what" it is doing
• the code can not always explain "why" it is doing something. That's where comments come it.

A good example would be something like this:

    connector = aiohttp.TCPConnector(ttl_dns_cache=None)
    # by setting ttl_dns_cache as None(never refresh) we ensure that there is no memory leak which was
    # otherwise occuring due to the ever growing _DNSCacheTable of the TCPConnector
    # reference link - https://github.com/aio-libs/aiohttp/issues/3684

Here the code has no way to explain WHY that dns cache has to be None. Hence this comment is useful. Unless there is a WHY which needs to be explained, there is no need for a comment.

Similarly comments may be used sometimes (I don't have enough experience doing this but I've seen other good people do it) to tell programmers that some parts of the code are off limits. Perhaps you need advanced mathematics to understand that part and it is easy to do wrong. In that scene you might put a comment saying something to the effect of "DO NOT TOUCH".

There is a talk by Kevlin Henney where he talks about some of these things.

[theSage21]

I have used Natural Docs instead of sphinx for creating Documentation from Code. Created Documentation is present inside Docs Folder.

please don't commit docs in the code. Docs are "generated" and so it's easier to host them on something like read the docs.

I'm not familiar with natural docs. If it's not too much work can we use the standard Sphinx setup?

[jatin56]

I have used Natural Docs instead of sphinx for creating Documentation from Code. Created Documentation is present inside Docs Folder.

please don't commit docs in the code. Docs are "generated" and so it's easier to host them on something like read the docs.

I'm not familiar with natural docs. If it's not too much work can we use the standard Sphinx setup?

I find using Natural docs much easier to use than Sphinx . I Just followed the Coding Standard Used in Natural Docs , Then it was just a one command to create Documentation . I have not used Sphinx much.

[rishabhKalakoti]

@jatin56 Learning something new is always good XD

[jatin56]

1. please keep review requests as small as possible. Makes it easier to review
2. please use docstrings as mentioned in previous review

Can You Give me a Example ?, like what needs to be changed in the code documentation

[theSage21]

well

1. there are 83 file changes right now. I don't think I have the time to go through that
2. this wiki explains what docstrings are please use those instead of random strings lying around the codebase

[theSage21]

Natural docs would be a good choice for you if it was a personal project that you were working on. Here's why I don't like it:

• one man show
• inactive project

Compare that to sphinx. You can explore the insights part of those projects on your own.

Since PyJudge is a community project + learning activity I'd like to avoid "one click solutions" since all you learn there is how to click rather than how the thing actually works. This is the kind of 'knowledge' that leads to absolute abominations like 'sophia the AI robot'.

[jatin56]

Okay ,
I think it would be better if we would set up some kind of Standard for Documentation for this Project. I got confused and used the standard i have been following. It would be beneficial for the people contributing in Future.

[theSage21]

Yes. I added comments to the issue.

I'm not sure if that is what you meant when you said standards for documentation. Is it?

[jatin56]

The changes are : Replacing multi line commit with Docstrings Merging new changes of master Remove Docs Folder included Before

[jatin56]

All the Lines which you have commented ,nothing new can be removed,or i should explain more?

[theSage21]

I meant remove the comment/docstring itself. There are around 30 ish things that can be removed since they are adding no value. I don't remember exactly since this was almost one month back

[theSage21]

This commit has been open for a month now without necessary feedback being implemented. I'd like to keep it open in case you're still working on the changes, but if you're exploring the codebase I'd like to close this PR and let someone else try their hand at the issue.

I'll be keeping this open till the end of week for the required changes to go in. Then I'll be closing it.