Open ISoirar opened 8 years ago
ghost
commented
8 years ago Hi Raros,
Thanks for comment. You can import GitHub project in Cloud9 and get all the files and edit them directly and update GitHub back.
It takes me 4mins... Also it's free...
By comments: plain text comments inside the code to highlight the architecture and dependencies between modules (not the code itself).
Will start little by little.
Kind regards Kevin
ISoirar
commented
8 years ago Ok, I see. Although I think notes about architecture and dependencies are best kept in documentation outside the code, for readability reasons. I figure that it would make it harder to read the code if you document not only directly code specific information such as behavior, types and so on, but also meta level information such as architecture and inter-module dependencies. Additionally, I think documentation generation is easier if you add .rst files in the docs folder rather than putting this information in the source. I might be mistaken though, so I'll just see how you'll do it. :smiley:
About using Cloud9: neither time nor cost were my concerns. I just thought it might be easier not adding this additional tool to the whole development process, as, for instance, you'd have to give permission to contributors individually. Now that you did upload it to Cloud9, with a link in #1, make sure you add anyone wanting to contribute and please make sure that it doesn't become a requirement. Everyone should be able to contribute to Py++11 without using Cloud9. Also consider adding the information of the optional Cloud9 project to the CONTRIBUTING.md file.
Response to @arita291's comment in #1:
The code definitely needs to be commented. However, there are multiple types of comments we will need in and about the source:
Documentation strings
The code obviously needs a better documentation coverage and I would highly suggest to put it directly into the source and extract it using Sphinx. I was thinking of something along the lines of Python's Docstring Conventions. However, at the moment I'm not quite sure how this will work with Sphinx' autodoc extension. I'll be looking into that and maybe someone can help me out with it.
Plain code comments
Python code is very self-explanatory, but right now the Py++11 source really needs quite a bit of effort to grasp what certain parts of the code are doing. I would like to add a few more comments so the gist of the code can be seen more easily.
Comments and notes for developers
Now I think this is most likely what the quote above was referring to. Personally, I'm a huge friend of plain text files, maybe with a little Markdown thrown into it. There is quite a lot achievable with these two things and I also like that this way, the comments and notes are accessible directly within the repository, which is especially good for anyone new who'd like to join the development process. Also, we don't spam the source with notes targeted at developers. These are the reasons why I would encourage the use of .md files inside the dev_tools folder, similar to what is already present.
All that being said, I've never used Cloud 9 before. Though from what I've read so far it seems to be pretty amazing! Nonetheless, I'm still of the opinion that simply forking the repository, adding notes via text files in the dev_tools folder and maintaining issues is more than enough to deal with this project. In fact, I think this is the simplest way to achieve this much power and flexibility over the development process.
If I missed something and or this isn't really answering what you were talking about @arita291, please feel free to correct me and go into more detail about your idea.