Merge pull request #39 from pro1code1hack/writing__comments

Writing  comments

Author: pro1code1hack

Base/11.Writing comments.py

@@ -0,0 +1,94 @@
+# Writing comments
+
+## Introduction
+
+When you write code in python it is important for it to be understandable by other people, and in order to reach this
+effect you can give variables and functions appropriate names, you can also help person who reads your code understand
+it by writing comments.
+
+In this guide you will learn:
+
+- Importance of commenting
+- How to write comments
+- How not to write comments
+
+## Importance of commenting
+
+An essential component of any program is comments. They might take the form of inline explanations that clarify
+complicated functions, module-level docstrings, or both. Let's examine the significance of code comments before delving
+into the various forms of comments. Think about the next two situations where a programmer choose not to comment their
+code:
+
+### When you're writing code for yourself
+
+Developers often forget what their code looks like when they're under a lot of pressure. Writing comments as you go is a
+great way to prevent this from happening.
+
+### When you're writing code for someone else
+
+Using comments throughout your code can help other developers. Comments help other devs skim through your code and gain
+an understanding of how it all works very quickly. You can help ensure a smooth transition by choosing to comment your
+code from the outset of a project.
+
+## How to write comments
+
+To write comment in python you simply have to put `#` before the text that you want to be commented, this part will be
+completely ignored by python:
+
+```python
+print("hi")  # print("bye")
+```
+
+#### Output:
+
+```
+hi
+```
+
+how you can see `#print("bye")` part is ignored and doesn't influence output.
+<br/>
+Comments must be short and to the point. Maximum 72 characters for inline comment is appropriate, if you surpass this
+value you should translate your comment to the next line.
+
+### Multiline comments
+
+Unfortunately, in python, you can't make multiline comments like in other languages, instead you can add more `#`s:
+
+```python
+# This is example
+# of multiline
+# commenting in python
+```
+
+there is another way of creating comment:
+
+```python
+"""
+this is another example
+of multiline comment 
+which is not really a comment
+"""
+```
+
+this is string that is not assigned by any of the variables so it is ignored by pythin,
+but you have to be careful with these things, because sometimes, when you comment function or methods this way, it
+might confuse people who read your code.
+
+## How not to write comments
+
+1. Avoid D.R.Y. comments(D.R.Y. stands for "don't repeat yourself"), your comments mustn't be redundant. There is no
+   need
+   to comment pieces of code tht speak for themselves:
+
+```python
+def foo():
+    a = 0
+    return a  # returns a
+```
+
+2. Avoid comments that are trying to hide problems of your code.
+3. Avoid rude comments:
+
+```python
+# This fucking code Sasha has written is yebala, needs to be fixed
+```

Base/11.Writing_comments.md

@@ -0,0 +1,71 @@
+### Contents
+
+1. Rename file and it's references
+2. Rename a variable(and not only) across the project
+3. Navigate to symbol
+4. Navigate to file
+5. Select the whole code
+6. Make your code beautiful
+7. Optimize import
+8. Find action
+9. Local file history
+10. Quick fixes
+11. Multiple cursors
+
+### 1.Rename file
+
+To rename a file and all it's references you simply have to right-click on the file and then refactor-->rename
+<br/>
+**Shortcut** - *shift f6*
+
+### 2.Rename symbol
+
+In order to change the name of a variable object or anything else, select the symbol right-click on it and then
+refactor-->rename.
+<br/>
+**Shortcut** - *shift f6*
+
+### 3.Navigate to symbol
+
+In order to navigate to any variable in your code use ***Shift-Ctrl-Alt-N***(windows) or ***Alt-Cmd-O***(mac). Then type
+the
+name you are looking for.
+
+### 4.Navigate to file
+
+In order to navigate to any file in your project use ***Shift-Ctrl-N***(windows) or ***Shift-Cmd-O***(mac). Then type
+the
+name you are looking for.
+
+### 5.Select the whole code
+
+To select the whole code in a file press ***Ctrl-A***(windows) or ***Cmd-A***(mac)
+
+### 6.Make your code beautiful
+
+select the code you want to reformat and press  ***Ctrl-Alt-L***(windows) or ***Cmd-Alt-L***
+
+### 7.Optimize import
+
+To optimize imports in a file simply press ***Ctrl+Alt+Shift+L***(windows) or ***Cmd+Alt+Shift+L***(mac)
+
+### 8.Find action
+
+If you can't remember how to call action, for example, navigate by symbol, you can just use one, find action by pressing
+***Ctrl+Shift+A***(windows) or ***Cmd+Shift+A***(mac) and typing the action you need.
+
+### 9.Local file history
+
+If you made something stupid in past and now want to return to that point there is a way of doing it through local
+history of the file. To open the history right-click on the file then Local History-->Show History
+
+### 10.Quick fixes
+
+Sometimes when pycharm shows you that something is wrong with a part of code by underlining it with the red line, if you
+select the problem part and press ***Alt-Enter***, pycharm will show you the list of fixes that might help.
+
+### 11.Multiple cursors
+
+If you will writing multiple identical or similar lines of code you can use multiple cursor be holding *Alt* and
+clicking
+on the places where you need additional cursor.

Base/12.PyCharm Guide.py

@@ -0,0 +1,65 @@
+# Debugging in pycharm
+
+To prepare PyCharm for debugging, you need to specify a so-called breakpoint. This is the line after which the debugger
+will start and the code will step through. Since our program is small, we will tell the debugger to start from the
+beginning. To put a breakpoint, you need to click the mouse to the left of the needed line and to the right of its
+number. A red circle will appear at this point, indicating that a pause will occur at this point. To remove the
+breakpoint, you need to click on the red circle again.
+
+![](images/debugging_break_point.png)
+
+Then you have to launch the debugger, in order to launch it you can either click on the debugger icon in up right corner
+or press *shift + f9* if you use windows or linux and *option + D* on mac.
+
+![](images/debugging_console.png)
+
+We now see two tabs: *Debugger* and *Console*. In the console, we see everything that the program has displayed so far.
+Since we stopped execution at the very beginning, the console will be empty for now. It is the debugger window that is
+of interest to us, since here we can track the change of all variables. As you can see, we already have a list of
+Special Variables, in which you can see the values of such utility variables as `__name__`.
+
+![](images/debugging_special_variables.png)
+
+To start tracking a new variable, enter the name of the variable to the input field and click on a plus icon. First, we
+will see the inscription name 'i' is not defined, which means that our variable has not even been created yet.
+
+![](images/dubugging_add_variable.png)
+![](images/debugging_name_not_defined.png)
+
+Let's then tell the debugger to process the next line of code. It is important to note here that there are 2 main
+ways of stepping: *step into* and *step over*.
+
+### step into
+
+When stepping into, the debugger will "enter" inside all functions and other constructs if it encounters them. So, if
+the debugger comes to calling some function func(), then it will go to the part of the code where its contents are
+described. To make one step into, press F7.
+
+### step over
+
+With the step over, the debugger will not “enter” all functions and other constructs, but will simply execute the
+entire code of the function without stopping and continue execution further. To make one step over, press F8.
+
+### Process itself
+
+In our example, it doesn't matter what to use, since we don't have any functions. So let's use the over step.
+When stepping through each line, we will go through the loop 9 times and see how the variable i changes 9
+times:
+<br/>
+
+*press F8*
+![](images/debugging_step_0.png)
+
+*press F8*, twice(because we go to the loop line itself firstly)
+![](images/debugging_step_1.png)
+
+*press F8*, twice(because we go to the loop line itself firstly)
+![](images/debugging_step_2.png)
+
+You can either stop debugging manually or wait until the debugger has processed all the lines in the program, which is
+almost never found in practice. You can also create multiple breakpoints.
+
+### Conclusion
+
+All in all, debugging is an indispensable thing in the development of real projects, because it is the most effective
+tool for finding errors.