88 Matching Annotations
  1. Mar 2020
    1. Should you place descriptions of code inside code comments or in text (paragraphs or lists) outside of the sample code? Note that readers who copy-and-paste a snippet gather not only the code but also any embedded comments. So, put any descriptions that belong in the pasted code into the code comments. By contrast, when you must explain a lengthy or tricky concept, you should typically place the text before the sample program.

      .

    2. Long paragraphs are visually intimidating. Very long paragraphs form a dreaded "wall of text" that readers ignore. Readers generally welcome paragraphs containing three to five sentences, but will avoid paragraphs containing more than about seven sentences.

      .

    3. In an active voice sentence, an actor acts on a target. That is, an active voice sentence follows this formula: Active Voice Sentence = actor + verb + target A passive voice sentence reverses the formula. That is, a passive voice sentence typically follows the following formula: Passive Voice Sentence = target + verb + actor

      .

    1. See http://mathesaurus.sf.net/ for another MATLAB®/NumPy cross-reference.

      Why linking to another of the same? If the reason is to provide a reference, I would change the title of this section and make this explicit.

    2. from numpy import *

      Generally, this is not recommended. Why recommending it here? Just because they would look more similar to how Matlab users do? If so, I believe the best approach is to teach the proper and recommended way, and not allow them to get their results without complying with Python standards.

    3. ‘array’ or ‘matrix’? Which should I use?

      If the answer is so simple and obvious, I wouldn't make a question out of it. Just introduce arrays, then. And then explain how they work when compared to Matlab's version.

      As a footnote, you may say "What about numpy matrices?" and give a short context.

    4. In MATLAB®, arrays have pass-by-value semantics, with a lazy copy-on-write scheme to prevent actually creating copies until they are actually needed. Slice operations copy parts of the array. In NumPy arrays have pass-by-reference semantics. Slice operations are views into an array.

      The title of the table are "differences," but the first sentence here is about a similarity.

    5. MATLAB® uses 1 (one) based indexing. The initial element of a sequence is found using a(1). See note INDEXING Python uses 0 (zero) based indexing. The initial element of a sequence is found using a[0].

      The first sentence of both columns are unnecessary.

    6. In MATLAB®, the basic data type is a multidimensional array of double precision floating point numbers. Most expressions take such arrays and return such arrays. Operations on the 2-D instances of these arrays are designed to act more or less like matrix operations in linear algebra. In NumPy the basic type is a multidimensional array. Operations on these arrays in all dimensionalities including 2D are element-wise operations. One needs to use specific functions for linear algebra (though for matrix multiplication, one can use the @ operator in python 3.5 and above).

      Sentences are too long. The same information can be said in a different, but lighter, way.

    7. MATLAB® and NumPy/SciPy have a lot in common. But there are many differences. NumPy and SciPy were created to do numerical and scientific computing in the most natural way with Python, not to be MATLAB® clones.

      Weird way of putting it. Are they similar or not? I'm specially confused about the third sentence - I had to read it 3x to understand it.

    1. NumPy supports a much greater variety of numerical types than Python does.

      I expected to read more on how comparable types are different from Python. Put in different words: what's the difference between type() and dtype()?

    1. The matrix product can be performed using the @ operator (in python >=3.5) or the dot function or method

      What's the recommended way? Based on my experience, people will use np.dot more often. Also because it's easy to spot bugs where you convert a matrix multiplication from a math formula and just uses *.

    1. You can save a NumPy array as a plain text file like a .csv or .txt file with np.savetxt.

      This is a place for organizing the hierarchy of the section. How many recommended ways I have for saving an array in disk? What are the practical differences? When to use each?

    2. You can save it as “filename.npy” with: >>>>>> np.save('filename', a) You can use np.load() to reconstruct your array. >>>>>> b = np.load('filename.npy')

      Weird that I use .npy just when loading. If the function supports saving with the extension in the name, I would add it in the example.

    3. handle NumPy binary files with a .npy file extension, and a savez function that handles NumPy files with a .npz file extension.

      What's the practical difference between the two extensions? What's the preferred/recommended way? Those are my first questions in this section.

    4. You will, at some point, want to save your arrays to disk and load them back without having to re-run the code.

      "re-run the code." What code? What does this do? Maybe suggest that this was an array that was generated after calling multiple functions, etc.

    5. For example, this is the mean square error formula (a central formula used in supervised machine learning models that deal with regression): Implementing this formula is simple and straightforward in NumPy: What makes this work so well is that predictions and labels can contain one or a thousand values. They only need to be the same size.

      Amazing use of images and colors!

    6. The primary difference between the two is that the new array created using ravel() is actually a reference to the parent array (i.e., a “view”). This means that any changes to the new array will affect the parent array as well.

      I've never knew this! Every time I needed it, I would google "the correct way" because often would not behave as I needed.

    7. generate random numbers (actually, repeatable pseudo-random numbers)

      I believe that this information is obvious for someone who knows the difference between the two. For those who don't know, it might add confusion. I'd remove it or leave it for a different paragraph, with some optional context.

    8. You might occasionally hear an array referred to as a “ndarray,” which is shorthand for “N-dimensional array.” An N-dimensional array is simply an array with any number of dimensions. You might also hear 1-D, or one-dimensional array, 2-D, or two-dimensional array, and so on. The NumPy ndarray class is used to represent both matrices and vectors. A vector is an array with a single dimension (there’s no difference between row and column vectors), while a matrix refers to an array with two dimensions. For 3-D or higher dimensional arrays, the term tensor is also commonly used.

      Again, another place for images.

  2. Feb 2020
    1. Need Discovery

      I see that this nomenclature (e.g. needs summary, job epics, blueprint) is widely used in documents across the organization. At this at this moment, from my first day ~4 months ago to this first day of Tech Leaders Program, it's not clear the difference between these documents. I wonder if there are ways to make this more explicit to people who haven't deeply understand this dojo page yet.

  3. Dec 2019
    1. Plan: planning work to deliver that solution. This includes breaking down a design into tasks, clarifying their dependencies and estimating these (i.e. a roadmap).

      If the first steps are done by someone who's not going to be the developer, ideally, the estimation step should include the developers (e.g., engineers, designers).

    2. We emphasize that analysis is applicable both to large projects and to a single simple task. Just as test-driven development is worthwhile even for simple changes, so analyis will pay dividends even for small script or a minor change to a website.

      Reminds me of README-Driven Development, associated to Test-Driven Development.