ch1-s1-ss1 pre-rdy

fancy-listings-preamble.tex

@@ -84,7 +84,7 @@
     keywordstyle=\color{codekeywords},
     morecomment=[l]{;}, % l is for line comment
     morecomment=[s]{/*}{*/}, % s is for start and end delimiter
-    basicstyle={\ttfamily\footnotesize},
+    basicstyle={\ttfamily\scriptsize},
     morekeywords={
      bset, macr,
       add,addi,and,andi,

j-spec.tex

@@ -16,6 +16,7 @@
 \usepackage{longtable}
 \usepackage{tikz}
 \usepackage{hyperref}
+\usepackage{forest}
 \usetikzlibrary{mindmap,trees}
 \input{fancy-listings-preamble}
 
@@ -126,7 +127,7 @@ TL;DR:
 
 Как именно всё работает? Если коротко, то слой за слоем накладывая абстракции. Программы на любом языке программирования исполняются на компьютере, то есть, так или иначе, задействуют процессор, оперативную память и прочие аппаратурные компоненты. Эти аппаратурные компоненты предоставляют для доступа к себе низкоуровневые интерфейсы, которые задействует операционная система, предоставляя в свою очередь интерфейс чуть проще программам, взаимодействующим с ней. Этот интерфейс взаимодействия с ОС мы для простоты будем называть Native API.
 
-С ОС взаимодействует JVM, то есть, используя Native API, нам становится всё равно, какая именно ОС установлена на компьютере, главное уметь выполняться на JVM. Это открывает простор для создания целой группы языков, они носят общее бытовое название JVM-языки, к ним относят Scala, Groovy, Kotlin и другие. Внутри JVM осуществляется управление памятью, существует механизм исполнения программ, специальный JIT\footnote{JIT, just-in-time - англ. в\'{о}время, прямо сейчас}-компилятор, генерирующий платформенно-зависимый код.
+С ОС взаимодействует JVM (\href{https://ru.m.wikipedia.org/wiki/Список_виртуальных_машин_Java}{Wikipedia: Список виртуальных машин Java}), то есть, используя Native API, нам становится всё равно, какая именно ОС установлена на компьютере, главное уметь выполняться на JVM. Это открывает простор для создания целой группы языков, они носят общее бытовое название JVM-языки, к ним относят Scala, Groovy, Kotlin и другие. Внутри JVM осуществляется управление памятью, существует механизм исполнения программ, специальный JIT\footnote{JIT, just-in-time - англ. в\'{о}время, прямо сейчас}-компилятор, генерирующий платформенно-зависимый код.
 
 JVM для своей работы запрашивает у ОС некоторый сегмент оперативной памяти, в котором хранит данные программы. Это хранение происходит «слоями»:
 \begin{enumerate}
@@ -189,7 +190,7 @@ Java Development Kit является изрядно дополненным сп
 \subsubsection{Структура проекта (пакеты, классы, метод main, комментарии)}
 Проекты могут быть любой сложности. Часто структуру проекта задаёт сборщик проекта, предписывая в каких папках будут храниться исходные коды, исполняемые файлы, ресурсы и документация. Без их использования необходимо задать структуру самостоятельно.
 
-\textbf{Простейший проект} состоит из файла исходного кода, который возможно скомпилировать и запустить как самостоятельный объект.
+\textbf{Простейший проект} чаще всего состоит из одного файла исходного кода, который возможно скомпилировать и запустить как самостоятельный объект. Отличительная особенность в том, что чаще всего это один или несколько статических методов в одном классе.
 
 Файл \code{Main.java} в этом случае может иметь следующий, минималистичный вид
 \begin{lstlisting}[language=Java,style=JCodeStyle]
@@ -200,17 +201,6 @@ public class Main {
 }
 \end{lstlisting}
 
-А скомпилировать и запустить его возможно без использования тяжеловесных сред разработки, введя в командной строке ОС две команды.
-\begin{lstlisting}[style=ASMStyle]
-ivan-igorevich@gb sources % ls
-Main.java
-ivan-igorevich@gb sources % javac Main.java 
-ivan-igorevich@gb sources % ls
-Main.class	Main.java
-ivan-igorevich@gb sources % java Main        
-Hello, world!
-\end{lstlisting}
-
 \textbf{Скриптовый проект} это достаточно новый тип проектов, он получил развитие благодаря растущей популярности Jupyter Notebook. Скриптовые проекты удобны, когда нужно отработать какую-то небольшую функциональность или пошагово пояснить работу какого-то алгоритма.
 \begin{figure}[H]
   \centering
@@ -232,8 +222,143 @@ Hello, world!
   \end{itemize}
 \end{itemize}
 
+Для примера был создан проект, содержащий два класса, находящихся в разных пакетах. Дерево проекта представлено на рис. \hrf{pic:simple-tree}, где папка с выходными (скомпилированными) бинарными файлами пуста, а файл README.md создан для лучшей демонстрации корня проекта.
+
+\begin{figure}[H]
+  \begin{forest}
+    for tree={
+      font=\ttfamily, grow'=0, child anchor=west,
+      parent anchor=south, anchor=west, calign=first,
+      edge path={
+        \noexpand\path [draw, \forestoption{edge}]
+        (!u.south west) +(7.5pt,0) |- node[fill,inner sep=1.25pt]
+        {} (.child anchor)\forestoption{edge label};
+      }, before typesetting nodes={
+        if n=1 {insert before={[,phantom]}} {} },
+      fit=band, before computing xy={l=15pt},
+    }
+    [Sample
+     [src
+      [ru
+       [gb
+        [jcore
+         [regular
+          [OtherClass.java]
+         ]
+         [sample
+          [Main.java]
+         ]
+        ]
+       ]
+      ]
+     ]
+     [out
+     ]
+     [README.md]
+    ]
+  \end{forest}
+  \label{pic:simple-tree}
+  \caption{Структура простого проекта}
+\end{figure}
+
+Содержимое файлов исходного кода представлено ниже.
+\begin{lstlisting}[language=Java,style=JCodeStyle]
+package ru.gb.jcore.sample;
+
+import ru.gb.jcore.regular.OtherClass;
+
+public class Main {
+    public static void main(String[] args) {
+        System.out.println("Hello, world!"); // greetings
+        int result = OtherClass.sum(2, 2);   // using a class from other package
+        System.out.println(OtherClass.decorate(result));
+    }
+}
+\end{lstlisting}
+\begin{lstlisting}[language=Java,style=JCodeStyle]
+package ru.gb.jcore.regular;
+
+public class OtherClass {
+    public static int sum(int a, int b) {
+        return a + b; // return without overflow check
+    }
+
+    public static String decorate(int a) {
+        return String.format("Here is your number: %d.", a);
+    }
+}
+\end{lstlisting}
+
+
 \subsubsection{Отложим мышки в сторону (CLI: сборка, пакеты, запуск)}
+Простейший проект возможно скомпилировать и запустить без использования тяжеловесных сред разработки, введя в командной строке ОС две команды:
+\begin{itemize}
+\item javac <Name.java> скомпилирует файл исходников и создаст в этой же папке файл с байт-кодом;
+\item java Name запустит скомпилированный класс (из файла с расширением \code{.class}).
+\end{itemize}
+
+\begin{lstlisting}[style=ASMStyle]
+ivan-igorevich@gb sources % ls
+Main.java
+ivan-igorevich@gb sources % javac Main.java 
+ivan-igorevich@gb sources % ls
+Main.class	Main.java
+ivan-igorevich@gb sources % java Main        
+Hello, world!
+\end{lstlisting}
+
+\begin{frm}
+  Скомпилированные классы всегда содержат одинаковые первые четыре байта, которые в шестнадцатиричном представлении формируют надпись «кофе, крошка».
+\begin{figure}[H]
+  \centering
+  \includegraphics[width=14cm]{jc-01-cafe-babe.png}
+\end{figure}
+\end{frm}
+
+Для компиляции более сложных проектов, необходимо указать компилятору, откуда забирать файлы исходников и куда складывать готовые файлы классов, а интерпретатору, откуда забирать файлы скомпилированных классов. Для этого существуют следующие ключи:
+\begin{itemize}
+\item javac:
+  \begin{itemize}
+  \item \code{-d} выходная папка (директория) назначения;
+  \item \code{-sourcepath} папка с исходниками проекта;
+  \end{itemize}
+\item java:
+  \begin{itemize}
+  \item \code{-classpath} папка с классами проекта;
+  \end{itemize}
+\end{itemize}
+
+Классы проекта компилируются в выходную папку с сохранением иерархии пакетов.
+
+\begin{lstlisting}[style=ASMStyle]
+ivan-igorevich@gb Sample % javac -sourcepath ./src -d out src/ru/gb/jcore/sample/Main.java
+ivan-igorevich@gb Sample % java -classpath ./out ru.gb.jcore.sample.Main
+Hello, world!
+Here is your number: 4.
+\end{lstlisting}
+
 \subsubsection{Документирование (Javadoc)}
+Документирование конкретных методов и классов всегда ложится на плечи программиста, потому что никто не знает программу и алгоритмы в ней лучше, чем программист. Утилита Javadoc избавляет программиста от необходимости осваивать инструменты создания веб-страниц и записывать туда свою документацию. Достаточно писать хорошо отформатированные комментарии, а остальное Javadoc возьмёт на себя.
+\begin{figure}[H]
+  \centering
+  \includegraphics[width=12cm]{jc-01-javadoc.png}
+  \caption{Часть cтраницы автосгенерированной документации}
+  \label{pic:}
+\end{figure}
+
+Чтобы просто создать документацию надо вызвать утилиту javadoc с набором ключей.
+\begin{itemize}
+  \item \code{ru} пакет, для которого нужно создать документацию;
+  \item \code{-d} папка (или директория) назначения;
+  \item \code{-sourcepath} папка с исходниками проекта;
+  \item \code{-cp} путь до скомпилированных классов;
+  \item \code{-subpackages} нужно ли заглядывать в пакеты-с-пакетами;
+  \item \code{-locale ru_RU} язык документации (для правильной расстановки переносов и разделяющих знаков);
+  \item \code{-encoding} кодировка исходных текстов программы;
+  \item \code{-docencoding} кодировка конечной сгенерированной документации.
+\end{itemize}
+
+
 
 \subsection*{Задания к семинару}
 \begin{itemize}

scenarios/jc-1-b.tex

@@ -4,6 +4,7 @@
 \usepackage{babel}
 \usepackage{fontspec}
 \input{../fancy-listings-preamble}
+\usepackage{forest}
 
 \makeatletter 
 \def\beamer@framenotesbegin{% at beginning of slide
@@ -12,6 +13,7 @@
       \gdef\beamer@notes{}% 
 }
 \makeatother
+\newcommand{\code}[1]{\small{\texttt{\detokenize{#1}}}\normalsize}
 
 % \setbeamertemplate{note page}{\pagecolor{yellow!5}\insertnote}
 % \setbeameroption{show notes on second screen=right}
@@ -178,6 +180,117 @@
 \end{frame}
 \note{...}
 
+\begin{frame}
+  \frametitle{Пакеты}
+  разделить на два слайда
+  сначала пакет с пакетами потом
+  стоящие стройными рядами коробки или контейнеры
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{Классы}
+  разделить на два слайда
+  сначала фото пустого школьного класса, потом
+  
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{метод мейн}
+  разделить на два слайда
+  псвм
+  показать точку входа как вход в пещеру
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{комментарии}
+  разделить на два слайда
+  можно как в редакции «комменты и лайки туда»
+  и слайд с типами комментариев
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{Структура простого проекта}
+    \begin{forest}
+    for tree={
+      font=\ttfamily, grow'=0, child anchor=west,
+      parent anchor=south, anchor=west, calign=first,
+      edge path={
+        \noexpand\path [draw, \forestoption{edge}]
+        (!u.south west) +(7.5pt,0) |- node[fill,inner sep=1.25pt]
+        {} (.child anchor)\forestoption{edge label};
+      }, before typesetting nodes={
+        if n=1 {insert before={[,phantom]}} {} },
+      fit=band, before computing xy={l=15pt},
+    }
+    [Sample
+     [src
+      [ru
+       [gb
+        [jcore
+         [regular
+          [OtherClass.java]
+         ]
+         [sample
+          [Main.java]
+         ]
+        ]
+       ]
+      ]
+     ]
+     [out
+     ]
+     [README.md]
+    ]
+  \end{forest}
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{Терминал}
+  показать папку с простейшим проектом из одного файла, скомпилировать, запустить.
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{Терминал}
+  тут, скорее всего, без лайв кода не обойтись, нужно открыть терминал и показать папку проекта, структуру проекта и содержимое файлов
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{Javadoc}
+  Пример автоматически сгенерированной документации
+  \includegraphics[width=12cm]{../pics/jc-01-javadoc.png}
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{утилита javadoc}
+  основные ключи и аргументы
+  \begin{itemize}
+  \item \code{-d docs}
+  \item \code{-sourcepath src}
+  \item \code{-cp out}
+  \item \code{-subpackages}
+  \item \code{ru}
+  \end{itemize}
+\end{frame}
+\note{...}
+
+\begin{frame}
+  \frametitle{куда же без особенностей работы с Windows?}
+  \begin{itemize}
+  \item \code{-locale ru_RU}
+  \item \code{-encoding utf-8}
+  \item \code{-docencoding cp1251}
+  \end{itemize}
+\end{frame}
+\note{...}
+
 \begin{frame}
   \frametitle{title}
 \end{frame}

scenarios/jc-1-c.tex

@@ -83,18 +83,72 @@
 \showslide{build/jc-1-b.pdf}
 Как я сказал в начале этого блока, шаблонные проекты, создаваемые сборщиками мы обсудим на следующей лекции, поэтому осталось только поговорить о том, из чего состоит обычный простой проект. Итак чаще всего, это  пакеты, классы, метод main, комментарии, ресурсы. Обо всём по порядку. Давайте сразу договоримся, что я сначала буду давать формальное понятие, а потом буду говорить, как его можно представить в более простом виде.
 
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
 Пакет - это пространство имён языка. Теоретически, как мы видели на примере простейшего проекта, класс может не находиться в пакете, но на практике такого положения дел не встретить. Например, в проекте из нескольких модулей классы без пакетов просто не будут найдены. Пакет - это некоторое место хранения и создания иерархии классов проекта. Проще всего представить пакет как папку на диске, тем более, что в файловой системе пакеты так и показываются. Но пакет - это чуть более сложная сущность. Для пакетов существуют модификаторы доступа, классы, находящиеся в одном пакете доступны друг другу даже если находятся в разных проектах (это как раз и есть отличие пакетов от папок на диске). Для нас пока достаточно, что пакеты объединяют классы по смыслу. У пакетов есть правила именования: обычно это обратное доменное имя (например, для гб.ру это будет ру.гб), название проекта, и далее уже внутренняя структура. Пакеты следует писать латинскими строчными буквами. Чтобы явно отнести класс к пакету недостаточно его просто туда положить, нужно ещё прописать в классе название пакета после специального оператора package.
 
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
 Класс - это основная единица исходного кода программы. Без класса не может начаться никакое программирование на языке Java. Даже скомпилированные файлы исходного кода имеют расширение .class. Что такое классы в терминах ООП вы уже знаете, но в Java классы - это более широкое понятие. Сама программа - это тоже класс. У классов также есть модификаторы доступа. Важно про классы - это то, что в файл с расширением джава следует класть только один класс и делать его публичным. Формально, язык не запрещает иметь в файле другие, не публичные классы, но писать так свои программы - это не толкьо дурной тон, но и весьма сбивающая с толку практика. У классов также есть правила именования. Название класса - это имя существительное в именительном падеже, написанное с заглавной буквы. Если требуется назвать класс в несколько слов, применяют так называемый upper camel case, то есть пишут слова строчными буквами, делая заглавной первую букву каждого слова.
 
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
 Метод мейн - это единственный в своём роде метод, который является точкой входа в программу. Метод является публичным, и должен находиться в публичном классе, то есть он доступен для исполнения любому желающему. А желает его исполнить JVM. Метод именно с такой сигнатурой (публичный, статический, ничего не возвращающий, принимающий массив строк) - это конвенция, договорённость, об именовании. JVM при старте программы среди всех пакетов и классов будет искать именно этот метод и будет передавать ему именно массив строк в качестве параметра. При создании этого метода важно полностью повторить его сигнатуру и обязательно написать его с название со строчной буквы.
 
-Комментарии - это часть кода, которую игнорирует компилятор при преобразовании исходного кода. Комментарии бывают:
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+С комментариями всё просто - это часть кода, которую игнорирует компилятор при преобразовании исходного кода. Комментарии бывают:
   \begin{itemize}
   \item \code{// comment} - до конца строки. Самый простой и самый часто используемый комментарий. Эти комментарии обычно поясняют неочевидные программные решения или сложные алгоритмы.
-  \item \code{/* comment */} - внутристрочный или многострочный. Никогда не используйте его внутри строк, несмотря на то, что это возможно. 
+  \item \code{/* comment */} - внутристрочный или многострочный. Никогда не используйте его внутри строк, несмотря на то, что это возможно. Обычно эти комментарии используют, чтобы оставить какое-нибудь длинное сообщение будущим поколениям программистов, которые будут поддерживать этот код.
-  \item \code{/** comment */} - комментарий-документация. Многострочный. Из него утилитой Javadoc создаётся веб-страница с комментарием.
+  \item \code{/** comment */} - комментарий-документация. Многострочный. Из него утилитой Javadoc создаётся веб-страница с комментарием. Самый полезный из всех полезных комментариев. Сейчас будем учиться делать из таких комментариев целые веб-сайты с программной документацией.
   \end{itemize}
 
+  Есть ещё такое собирательное понятие, как ресурсы, но его, возможно не следует рассматривать прямо сейчас потому что оно не является обязательным для вообще любого проекта, в отличие от пакетов, классов и комментариев. Работу с ресурсами мы разберём когда будем беседовать о более сложных проектах.
+
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+Для дальнейших упражнений на сегодняшнем уроке нам понадобится небольшой проект, буквально из двух классов в двух пакетах, без каких-то ограничений видимости и других усложнений. На основе этого проекта мы и поговорим об оставшихся на сегодня двух несложных темах - терминальная сборка и генерация документации. Дерево проекта представлено на слайде, где папка с выходными (скомпилированными) бинарными файлами пуста, а файл README.md создан для лучшей демонстрации корня проекта.
+
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+Итак. У нас был простейший проект, написать его было элементарно, что там, простой хелловорлд, скомпилировать и запустить его также просто. Нам понадобится утилита javac из состава JDK которая скомпилирует из текста программы байт-код, и утилита java из состава JRE которая этот байт-код сможет интерпретировать. То есть очевидно, и мы просто проговорим это дополнительно, что простому пользователю для запуска программы не нужен весь тяжёлый ЖДК. Показываем работу следующими командами
+\begin{verbatim}
+ ls
+ javac Main.java
+ ls
+ java Main
+\end{verbatim}
+Также существует забавный факт, что скомпилированные джава классы всегда содержат одинаковые первые 4 байта, которые в 16тиричном представлении формируют надпись «кофе, крошка», cafe babe.
+(открыть мейн.класс в хекс-редакторе, показать)
+
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+Для компиляции более сложных проектов, содержащих каике-то иерархические структуры из пакетов и классов, необходимо указать компилятору, откуда забирать файлы исходников (сорспас) и куда класть готовые классы (д может быть расшифрован как директория или как дестинейшн - назначение), а интерпретатору, откуда забирать файлы скомпилированных классов (класпас). Как хорошо видно среди только что написанных букв, для этого достаточно через пробел написать соответствующие ключи компиляции и запуска. Конечно, писать каждый раз эти ключи довольно утомительно и для автоматизации этого процесса придумали сборщики проектов, но всегда круто знать и уметь делать вещи в отсутствие сложного инструментария. Показываем работу следующими командами
+\begin{verbatim}
+javac -sourcepath ./src -d out src/ru/gb/jcore/sample/Main.java
+java -classpath ./out ru.gb.jcore.sample.Main
+\end{verbatim}
+
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+И к последней на сегодня теме, которая мочему-то вызывает у многих даже активно практикующих программистов отторжение. К самому полезному для передачи опыта между программистами и командами программистов. К документации на свой код. Конечно, особенно ярые противники описывать свою работу сейчас возмутятся, мол, я ж программист, пусть программную документацию пишут технические писатели. Но если подумать, то техпис фактически всё равно придёт к вам, программисту, за разъяснениями, что именно делает тот или иной фрагмент кода. А комментарии к коду всё равно писать, да и техпису, скорее всего придётся отвечать в текстовом виде, так почему бы не облегчить себе жизнь сразу, документируя свой код по мере написания, например, между спринтами. 
+
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+Чтобы просто создать документацию надо вызвать утилиту javadoc с небольшим количеством ключей, давайте их разберём. Уже знакомый нам ключ -d означающий папку (или директорию, кому как больше нравится) в которую следует положить готовую документацию. Помним, ключ легко запомнить, если расшифровать его как дестинейшн, назначение. -sourcepath означает папку, где лежат исходники проекта, как мы помним, в исходниках мы пишем те самые комментарии, которые потом можно преобразовать в джавадок. -cp говорит о том, где лежат готовые скомпилированные классы, эта информация нужна, чтобы понять, как программа в итоге скомпилировалась, что в ней задействовано, что как связано и прочее. -subpackages говорит о том, что надо взять не только указанный далее пакет, но и все его подпакеты рекурсивно. Ну и, собственно, пакет, для которого нужно создать документацию, ru. Показываем работу следующими командами:
+\begin{verbatim}
+javadoc -d docs -sourcepath src -cp out -subpackages ru
+\end{verbatim}
+Если нужно сгенерировать документацию к конкретному пакету, например, если вы хотите разложить их по разным папкам, то надо указатеь его полный адрес, и, вероятно, убрать ключ subpackages
+
+% -----------------------------------------------------------------------------------
+\showslide{build/jc-1-b.pdf}
+Чтобы учесть то, что происходитс ОС Windows надо чуть больше, поскольку так исторически сложилось, что у Windows есть проблемки с локалью. Поскольку все программы на Java пишутя в кодировке UTF-8, а основная кодировка всех приложений, работающих под ОС виндоус это ср1251, то при создании документации стандартными средствами итоговые веб-страницы создаются на клингонском. Чтобы перевести их на земной кириллический, нужно добавить три ключа - указать какая локаль установлена -locale, в какой кодировке исходный текст  -encoding utf-8, в какой кодировке должен быть итоговый документ  -docencoding cp1251. Показываем работу следующими командами:
+\begin{verbatim}
+javadoc -locale ru_RU -encoding utf-8 -docencoding cp1251 \
+ -d docs -sourcepath src -cp out -subpackages ru
+\end{verbatim}
+Поскольку я сейчас не с виндоусом, то такие настройки наоборот, сломают отображение.
 
 \end{document}