Skip to content

Commit

Permalink
Missing word (have) and typos
Browse files Browse the repository at this point in the history
  • Loading branch information
Naereen authored Apr 1, 2017
1 parent 269600c commit 74581c3
Showing 1 changed file with 11 additions and 10 deletions.
21 changes: 11 additions & 10 deletions faq/underscore-convention.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,15 @@ instead of
def sigmoid(self, z):
return 1.0 / (1.0 + np.exp(-z))

The short answer is, the trailing underscore (`self.gamma_`) in class attributes is a scikit-learn convention to denote "estimated" or "fitted" attributes. The leading underscores are (`_sigmoid(self, z)`) denote private methods that the user shouldn't bother with.
The short answer is, the trailing underscore (`self.gamma_`) in class attributes is a scikit-learn convention to denote "estimated" or "fitted" attributes.
The leading underscores are (`_sigmoid(self, z)`) denote private methods that the user should not bother with.


In brief: As a reader, you can safely ignore those underscores, however, if you are curious about their intention, please read on!

## Leading underscores in class methods

The usage of underscores for naming class methods is a common Python convention to distinguish between private and public methods. Basically, you don't want the user to worry about these private methods, which is why they don't appear in the help menu.
The usage of underscores for naming class methods is a common Python convention to distinguish between private and public methods. Basically, you do not want the user to worry about these private methods, which is why they do not appear in the help menu.

class MyClass(object):
def __init__(self, param='some_value'):
Expand Down Expand Up @@ -67,7 +68,7 @@ The usage of underscores for naming class methods is a common Python convention

* Note that `__init__` is an exception, `__init__` is a special method that is required to initialize a class.

Let’s initialize a new object and call this public class:
Let us initialize a new object and call this "public" class:

>>> MyObj = MyClass()
>>> MyObj.public()
Expand All @@ -81,7 +82,7 @@ The single underscore in `_indicate_private` indicates privacy. Typically, priva

- Please keep in mind that calling private methods is at your own risk; the developers usually take no responsibilities for odd things that may happen if you call private methods as a user.

The indication of privacy is a bit stronger if we use 2 preceding underscores, for example, calling the `__pseudo_private` method directly like a regular method doesn’t work anymore:
The indication of "privacy" is a bit stronger if we use 2 preceding underscores, for example, calling the `__pseudo_private` method directly like a regular method does not work anymore:

>>> MyObj.__pseudo_private()
---------------------------------------------------------------------------
Expand All @@ -91,7 +92,7 @@ The indication of “privacy” is a bit stronger if we use 2 preceding undersco

AttributeError: 'MyClass' object has no attribute '__pseudo_private'

To call the a private methods that is prefaced with 2 underscores, we need to adhere to the name mangling rules; that is, we need to add a `_classname` prefix, to call the method, for example,
To call the a private methods that is prefaced with 2 underscores, we need to adhere to the "name mangling" rules; that is, we need to add a `_classname` prefix, to call the method, for example,

>>> MyObj._MyClass__pseudo_private()
'really private method'
Expand All @@ -100,16 +101,16 @@ To call the a private methods that is prefaced with 2 underscores, we need to ad

## Class attributes with trailing underscores

In contrast to the leading underscore, the trailing underscores in class attributes don't any "technical" effects. In fact, this is just a convention that I adopted from scikit-learn out of habit.
In contrast to the leading underscore, the trailing underscores in class attributes do not have any "technical" effects. In fact, this is just a convention that I adopted from scikit-learn out of habit.

Here are two excerpts from the scikit-learn [developer/contributor documentation](http://scikit-learn.org/stable/developers/):

> Attributes that have been estimated from the data must always have a name ending with trailing underscore, for example, the coefficients of some regression estimator would be stored in a coef_ attribute after fit has been called.
> Attributes that have been estimated from the data must always have a name ending with trailing underscore `_`, for example, the coefficients of some regression estimator would be stored in a `coef_` attribute after `fit()` has been called.

> Also it is expected that parameters with trailing _ are not to be set inside the ``__init__`` method. All and only the public attributes set by fit have a trailing _. As a result the existence of parameters with trailing _ is used to check if the estimator has been fitted.
> Also it is expected that parameters with trailing underscore `_` are not to be set inside the ``__init__`` method. All and only the public attributes set by `fit()` have a trailing `_`. As a result the existence of parameters with trailing `_` is used to check if the estimator has been fitted.
To see it in action, let's create a primitive `Estimator`:
To see it in action, let us create a primitive `Estimator`:

class MyEstimator():
def __init__(self):
Expand All @@ -118,7 +119,7 @@ To see it in action, let's create a primitive `Estimator`:
def fit(self):
self.fit_param_ = 0.1

Intuitively, attributes that are in `__init__` are accessible after we initialized a new object
Intuitively, attributes that are in `__init__` are accessible after we initialized a new object:

>>> est = MyEstimator()
>>> est.param
Expand Down

0 comments on commit 74581c3

Please sign in to comment.