This document discusses guidelines for designing application programming interfaces (APIs). It outlines key characteristics of good APIs, including being easy to learn and memorize, leading to readable code, being hard to misuse, and being easy to extend. The document then discusses specific design principles and guidelines for APIs, such as using unambiguous and self-explanatory names, avoiding abbreviations, and striving for minimal yet complete APIs. Examples from Qt and other APIs are provided to illustrate both good and bad API design practices.
The document summarizes key principles for designing application programming interfaces (APIs). It discusses characteristics of good APIs, including being easy to learn and memorize, leading to readable code, being hard to misuse, being easy to extend, and being complete. It also covers the API design process and specific guidelines for API design.
This document provides an overview of REST APIs and automated API documentation solutions. It discusses REST architecture and best practices for documenting REST APIs. It also covers popular automated documentation solutions like Swagger and RAML that can generate reference documentation from API specifications. The document demonstrates how to use Swagger and RAML specifications to automatically generate API documentation websites and interactive consoles. It compares the pros and cons of Swagger versus RAML and provides examples of professionally designed API documentation websites.
API Workshop: Deep dive into code samplesTom Johnson
See http://idratherbewriting.com for more details. This was the third slidedeck I used in my presentation. Most of these slides repeat what I presented as a soap! conference webinar in Poland.
This document provides an introduction to Java programming, including setting up a development environment. It discusses downloading and installing the Java Development Kit (JDK) and Eclipse integrated development environment. It then provides an overview of key concepts in the Java language and platform, such as object-oriented programming, the Java compiler, Java virtual machine, garbage collection, and Java Development Kit. The document is intended to help new Java developers get started with building Java applications.
Automation testing involves automating manual testing processes to test applications and systems. Selenium is an open source tool that is commonly used for automation testing of web applications. It supports cross-browser testing and has components like Selenium IDE, WebDriver, and Grid. Some key features of Selenium include being free, having a large user community, and supporting multiple programming languages.
The document summarizes key principles for designing application programming interfaces (APIs). It discusses characteristics of good APIs, including being easy to learn and memorize, leading to readable code, being hard to misuse, being easy to extend, and being complete. It also covers the API design process and specific guidelines for API design.
This document provides an overview of REST APIs and automated API documentation solutions. It discusses REST architecture and best practices for documenting REST APIs. It also covers popular automated documentation solutions like Swagger and RAML that can generate reference documentation from API specifications. The document demonstrates how to use Swagger and RAML specifications to automatically generate API documentation websites and interactive consoles. It compares the pros and cons of Swagger versus RAML and provides examples of professionally designed API documentation websites.
API Workshop: Deep dive into code samplesTom Johnson
See http://idratherbewriting.com for more details. This was the third slidedeck I used in my presentation. Most of these slides repeat what I presented as a soap! conference webinar in Poland.
This document provides an introduction to Java programming, including setting up a development environment. It discusses downloading and installing the Java Development Kit (JDK) and Eclipse integrated development environment. It then provides an overview of key concepts in the Java language and platform, such as object-oriented programming, the Java compiler, Java virtual machine, garbage collection, and Java Development Kit. The document is intended to help new Java developers get started with building Java applications.
Automation testing involves automating manual testing processes to test applications and systems. Selenium is an open source tool that is commonly used for automation testing of web applications. It supports cross-browser testing and has components like Selenium IDE, WebDriver, and Grid. Some key features of Selenium include being free, having a large user community, and supporting multiple programming languages.
The document provides an introduction to programming with C# and the Visual Studio environment. It discusses that C# is an object-oriented language created by Microsoft to build a variety of applications that run on the .NET framework. It also describes the .NET framework, which includes the common language runtime that compiles C# code into intermediate language code and executes it. Finally, it introduces Visual Studio as an integrated development environment for creating C# applications and its key components like solutions and projects.
Selenium basic questions and answers
Selenium basic questions and answers
Selenium basic questions and answers
Selenium basic questions and answersSelenium basic questions and answers
Selenium basic questions and answers
A Review Paper on Kotlin Programming Languageijtsrd
This document discusses Kotlin, an open-source programming language that is designed to interoperate with Java but intended to help reduce issues like verbosity and null-pointer exceptions. It provides an overview of Kotlin, comparing it to Java, and outlines some of Kotlin's key features such as concise syntax, null safety, and interoperability with existing Java code and libraries. The document also discusses some advantages of Kotlin such as increased productivity and less bugs compared to Java, as well as some disadvantages like differences from Java and limited availability of Kotlin professionals. Overall, it presents Kotlin as an improved option to Java for application development.
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.
C# and java comparing programming languagesShishir Roy
The document provides an in-depth comparison of the C# and Java programming languages. It discusses many similarities between the two languages, such as both using garbage collection and being fully object-oriented. The document also examines differences, such as C# learning from Java's strengths and weaknesses. Overall, the document aims to help readers understand the motivations behind the languages' designs and make informed choices about which to use for different situations.
International Journal of Engineering Research and DevelopmentIJERD Editor
Electrical, Electronics and Computer Engineering,
Information Engineering and Technology,
Mechanical, Industrial and Manufacturing Engineering,
Automation and Mechatronics Engineering,
Material and Chemical Engineering,
Civil and Architecture Engineering,
Biotechnology and Bio Engineering,
Environmental Engineering,
Petroleum and Mining Engineering,
Marine and Agriculture engineering,
Aerospace Engineering.
The document argues that the distinction between source code and object code is a false dichotomy. It provides several examples to illustrate that:
1) Source and object code are relative terms, as the output of one program can be input to another. Programs typically undergo multiple transformations from higher to lower-level representations.
2) Even binary machine code can be read by humans with disassemblers, and interpreted languages can execute human-readable source code directly without compiling.
3) The boundaries between human-readable and executable code are blurred, as emulators and virtual machines allow otherwise non-executable code to run. All computer code ultimately expresses the same underlying algorithms and logic.
This document introduces CETPA as a missing link to help bridge the gap between engineering graduates and jobs in the technology sector. It provides an overview of CETPA's training programs in computer programming concepts, data structures, web technology, and projects. The document also discusses the Java programming language and its versions, and explains concepts like generations of programming languages, Java virtual machines, and Java application programming interfaces.
VGuru(TM), brought to you by SkandVLSI, is first of its kind world-class product, in the field of VLSI education. VGuru is a software product that helps, guides, and makes you prficient like a GURU, who is always by your side to see you succeed. With VGuru, you can Learn<=> Practice <=> Teach Verilog and VHDL with INDUSTRY BEST PRACTICES and other VLSI concepts like, Logic Gates input/output waveforms, CMOS logic gates, CMOS Stick diagrams etc.
BE INDUSTRY READY with VGuru, along with Learning for Academic Courses.
The document contains interview questions from various companies like HCL, Emids, Manhattan, 3PLM, Zolipe Solutions, Synchronoss, and Cognizant for positions ranging from 2-3 years of experience in Selenium testing. The questions cover a wide range of topics including Selenium, manual testing, Java, SQL, algorithms, data structures and design patterns. Common questions asked relate to frameworks, test automation lifecycles, handling dynamic elements, test case design techniques, and debugging skills.
This document provides an introduction to programming concepts like what a computer program is, the program development cycle, and basic C++ syntax. It includes a first simple C++ program that prints "Hello World" to demonstrate writing, compiling, and running a program. Variables and constants are introduced. The document is teaching material for a course on programming fundamentals in C++.
API Documentation Workshop tcworld India 2015Tom Johnson
This is a workshop I gave on API documentation at tcworld India 2015. The workshop covers 3 main areas:
- General overview of API documentation
- Deep dive into REST API documentation
- Deep dive into Javadoc documentation
The document provides instructions for programming a UAV DevBoard using a PIC microcontroller. It outlines the necessary equipment including an ICD2 programmer, MPLAB IDE software, and MPLAB C compiler. It describes downloading and installing the software, connecting the ICD2, opening a project in MPLAB IDE, programming the board, and common errors that may occur. The process involves installing software, connecting hardware, selecting options in MPLAB IDE, building and programming a project, and debugging firmware.
This document provides an overview of object-oriented programming concepts and Java programming. It introduces topics like classes, objects, inheritance, polymorphism, exception handling, input/output streams, events, applets, serialization, databases, networking, threading and more. The document is intended to teach OOP concepts independently of a specific language using examples in Java and C++. It emphasizes that learning to use the Java class libraries and object-oriented design are the main challenges for Java programmers.
This document discusses the Spring framework. It defines framework as software that provides predefined support for application development. Spring is described as an open source, lightweight application framework that uses inversion of control (IOC) and dependency injection (DI). The document outlines the different versions and modules of Spring, including core, DAO, ORM, context, AOP, and web modules. It also discusses Spring architecture, the types of frameworks (invasive and non-invasive), and the resources needed to develop a Spring application.
The document provides information on AppFuse, an open-source Java web application framework. It describes AppFuse as a project skeleton that eliminates initial setup time and includes additional classes and files implementing common features. The document also lists some key features included in AppFuse like authentication, authorization, file uploads and templated layouts. It notes that these out-of-the-box features distinguish AppFuse from other code generation frameworks.
This document discusses using REST APIs for resources beyond basic CRUD operations. It provides examples of representing shopping carts and book printing as RESTful resources. For shopping carts, it describes how to create, read, update, delete, and calculate charges for cart items. For book printing, it outlines how to download a PDF, order a print job, check status, and cancel orders. The document argues that RESTful design should focus on resources and services over CRUD actions.
HTML5 and CSS3 have arrived and they are redefining rich, standards-based web development. Features previously the exclusive domain of browser plug-ins can now be added to web applications as easily as images. Understanding the new power that these standards define, as well as the rapidly increasing power and speed of JavaScript in modern browsers and devices is essential. These slides accompany a full-day workshop, where attendees are guided through the new features in HTML5 and CSS3, with special attention to how these technologies can be used today in new and old browsers.
The document provides an introduction to programming with C# and the Visual Studio environment. It discusses that C# is an object-oriented language created by Microsoft to build a variety of applications that run on the .NET framework. It also describes the .NET framework, which includes the common language runtime that compiles C# code into intermediate language code and executes it. Finally, it introduces Visual Studio as an integrated development environment for creating C# applications and its key components like solutions and projects.
Selenium basic questions and answers
Selenium basic questions and answers
Selenium basic questions and answers
Selenium basic questions and answersSelenium basic questions and answers
Selenium basic questions and answers
A Review Paper on Kotlin Programming Languageijtsrd
This document discusses Kotlin, an open-source programming language that is designed to interoperate with Java but intended to help reduce issues like verbosity and null-pointer exceptions. It provides an overview of Kotlin, comparing it to Java, and outlines some of Kotlin's key features such as concise syntax, null safety, and interoperability with existing Java code and libraries. The document also discusses some advantages of Kotlin such as increased productivity and less bugs compared to Java, as well as some disadvantages like differences from Java and limited availability of Kotlin professionals. Overall, it presents Kotlin as an improved option to Java for application development.
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.
C# and java comparing programming languagesShishir Roy
The document provides an in-depth comparison of the C# and Java programming languages. It discusses many similarities between the two languages, such as both using garbage collection and being fully object-oriented. The document also examines differences, such as C# learning from Java's strengths and weaknesses. Overall, the document aims to help readers understand the motivations behind the languages' designs and make informed choices about which to use for different situations.
International Journal of Engineering Research and DevelopmentIJERD Editor
Electrical, Electronics and Computer Engineering,
Information Engineering and Technology,
Mechanical, Industrial and Manufacturing Engineering,
Automation and Mechatronics Engineering,
Material and Chemical Engineering,
Civil and Architecture Engineering,
Biotechnology and Bio Engineering,
Environmental Engineering,
Petroleum and Mining Engineering,
Marine and Agriculture engineering,
Aerospace Engineering.
The document argues that the distinction between source code and object code is a false dichotomy. It provides several examples to illustrate that:
1) Source and object code are relative terms, as the output of one program can be input to another. Programs typically undergo multiple transformations from higher to lower-level representations.
2) Even binary machine code can be read by humans with disassemblers, and interpreted languages can execute human-readable source code directly without compiling.
3) The boundaries between human-readable and executable code are blurred, as emulators and virtual machines allow otherwise non-executable code to run. All computer code ultimately expresses the same underlying algorithms and logic.
This document introduces CETPA as a missing link to help bridge the gap between engineering graduates and jobs in the technology sector. It provides an overview of CETPA's training programs in computer programming concepts, data structures, web technology, and projects. The document also discusses the Java programming language and its versions, and explains concepts like generations of programming languages, Java virtual machines, and Java application programming interfaces.
VGuru(TM), brought to you by SkandVLSI, is first of its kind world-class product, in the field of VLSI education. VGuru is a software product that helps, guides, and makes you prficient like a GURU, who is always by your side to see you succeed. With VGuru, you can Learn<=> Practice <=> Teach Verilog and VHDL with INDUSTRY BEST PRACTICES and other VLSI concepts like, Logic Gates input/output waveforms, CMOS logic gates, CMOS Stick diagrams etc.
BE INDUSTRY READY with VGuru, along with Learning for Academic Courses.
The document contains interview questions from various companies like HCL, Emids, Manhattan, 3PLM, Zolipe Solutions, Synchronoss, and Cognizant for positions ranging from 2-3 years of experience in Selenium testing. The questions cover a wide range of topics including Selenium, manual testing, Java, SQL, algorithms, data structures and design patterns. Common questions asked relate to frameworks, test automation lifecycles, handling dynamic elements, test case design techniques, and debugging skills.
This document provides an introduction to programming concepts like what a computer program is, the program development cycle, and basic C++ syntax. It includes a first simple C++ program that prints "Hello World" to demonstrate writing, compiling, and running a program. Variables and constants are introduced. The document is teaching material for a course on programming fundamentals in C++.
API Documentation Workshop tcworld India 2015Tom Johnson
This is a workshop I gave on API documentation at tcworld India 2015. The workshop covers 3 main areas:
- General overview of API documentation
- Deep dive into REST API documentation
- Deep dive into Javadoc documentation
The document provides instructions for programming a UAV DevBoard using a PIC microcontroller. It outlines the necessary equipment including an ICD2 programmer, MPLAB IDE software, and MPLAB C compiler. It describes downloading and installing the software, connecting the ICD2, opening a project in MPLAB IDE, programming the board, and common errors that may occur. The process involves installing software, connecting hardware, selecting options in MPLAB IDE, building and programming a project, and debugging firmware.
This document provides an overview of object-oriented programming concepts and Java programming. It introduces topics like classes, objects, inheritance, polymorphism, exception handling, input/output streams, events, applets, serialization, databases, networking, threading and more. The document is intended to teach OOP concepts independently of a specific language using examples in Java and C++. It emphasizes that learning to use the Java class libraries and object-oriented design are the main challenges for Java programmers.
This document discusses the Spring framework. It defines framework as software that provides predefined support for application development. Spring is described as an open source, lightweight application framework that uses inversion of control (IOC) and dependency injection (DI). The document outlines the different versions and modules of Spring, including core, DAO, ORM, context, AOP, and web modules. It also discusses Spring architecture, the types of frameworks (invasive and non-invasive), and the resources needed to develop a Spring application.
The document provides information on AppFuse, an open-source Java web application framework. It describes AppFuse as a project skeleton that eliminates initial setup time and includes additional classes and files implementing common features. The document also lists some key features included in AppFuse like authentication, authorization, file uploads and templated layouts. It notes that these out-of-the-box features distinguish AppFuse from other code generation frameworks.
This document discusses using REST APIs for resources beyond basic CRUD operations. It provides examples of representing shopping carts and book printing as RESTful resources. For shopping carts, it describes how to create, read, update, delete, and calculate charges for cart items. For book printing, it outlines how to download a PDF, order a print job, check status, and cancel orders. The document argues that RESTful design should focus on resources and services over CRUD actions.
HTML5 and CSS3 have arrived and they are redefining rich, standards-based web development. Features previously the exclusive domain of browser plug-ins can now be added to web applications as easily as images. Understanding the new power that these standards define, as well as the rapidly increasing power and speed of JavaScript in modern browsers and devices is essential. These slides accompany a full-day workshop, where attendees are guided through the new features in HTML5 and CSS3, with special attention to how these technologies can be used today in new and old browsers.
Spring is a flexible Java framework that provides solutions to commonly occurring problems in Java projects. It uses an inversion of control container and aspect-oriented programming to increase modularity. Spring supports features like dependency injection, MVC web development, and integration with other technologies like JPA, Hibernate and JDBC. Some key benefits of Spring include loose coupling of components, reducing boilerplate code, and aiding testability.
HTML documents consist of HTML tags and text that are used to structure and markup web page content. HTML tags come in pairs with opening and closing tags, are case insensitive, and always surround element content. The basic structure of an HTML document includes a <head> section for metadata and a <body> section for visible page content.
Hibernate is a framework used to develop Java applications to interact with database servers. It resolves issues with JDBC like handling exceptions and closing connections. The key components of Hibernate are the configuration file, POJO classes, and mapping files. The configuration file contains database connection details. POJO classes represent records as objects. Mapping files map classes to tables and properties to columns. To use Hibernate, these components are configured along with the required jar files.
The document discusses REST (REpresentational State Transfer), a style of architecture for building web services. It defines REST and RESTful web services, describes the key REST principles of using resources and uniform interfaces. It explains why REST is preferable to SOAP in many cases due to being lightweight, supporting multiple data formats and better performance. The document also provides guidance on when each approach is better suited and compares SOAP vs REST. It introduces JAX-RS as a Java API for building RESTful web services and some common implementations like Jersey.
JavaOne 2011: Migrating Spring Applications to Java EE 6Bert Ertman
The Spring Framework has no-doubt played a major role in evolving the way we write enterprise applications on the Java platform today. However, it is still a proprietary framework owned by a single company. The age of having to rely on such proprietary frameworks in order to develop decent enterprise applications is now over and Java EE 6 has become an even easier way to develop enterprise applications based on standards which makes it the best choice for any enterprise application. In this session you will experience how to migrate a typical full stack Spring application to a standards based, completely portable, Java EE 6 application including integration tests.
This document discusses database management systems and SQL. It provides examples of creating tables, inserting and retrieving data using commands like SELECT, UPDATE, and DELETE. It also covers SQL sublanguages, data types, logical operators, and pattern matching operators. Key points include that a DBMS manages a database using software, SQL is the standard language used to communicate with databases, and tables are used to store data in rows and columns.
This document provides guidance on designing RESTful APIs. It recommends using nouns instead of verbs, keeping URLs simple with only two endpoints per resource, and following conventions from leading APIs. Complex variations and optional parameters should be "swept behind the '?'." The document emphasizes designing for application developers by making APIs intuitive, consistent and complete while also accommodating exceptional clients. It suggests adding an API virtualization layer to handle complexity.
Introduction to the Spring Framework:
Generar description
IoC container
Dependency Injection
Beans scope and lifecycle
Autowiring
XML and annotation based configuration
Additional features
Amrendra Kumar Sandilya is seeking a position that allows him to further develop his skills in IT operations and project management. He has over 8 years of experience in IT services and currently works as an IT Operations Manager at IndiGo Aviation in Gurgaon, where he is responsible for level 2 escalations, SLA management, and overseeing various IT infrastructure and support teams. Previously, he held roles such as WMG & VIP Team Lead at Cairn India and Remote Support North Lead at Genpact.
This document provides a summary of the key points from the document "Consumer-Centric API Design".
1. The document discusses best practices for designing APIs that are consumer-centric and easy for developers to use. It emphasizes data abstraction, using common HTTP methods and patterns, and focusing on the needs of API consumers.
2. The author advocates designing APIs around core CRUD concepts to abstract complex business logic and data structures. Real-world examples show both good and bad approaches to data abstraction.
3. Additional chapters will cover topics like HTTP requests and responses, API versioning, authentication, permissions, documentation and testing. The goal is for readers to understand how to build APIs that third-party developers will enjoy
Secure software development has become a priority for all organizations whether they build their own software or outsource. And code analysis is becoming the de facto choice to introduce secure development as well as measure inherent software risk.
The document discusses the pros and cons of using open source software in projects. It notes that open source code comes with various licenses like GPL, BSD, and MIT that differ in how they can be used. While open source lacks perceived accountability, it actually has governance structures. The document aims to provide context on open source licensing and use within the scope of incorporating external code into a project. It addresses common concerns about open source like licensing complexity but clarifies the intent is to protect author rights, not hinder code use.
With Microsoft prePress, you can access just-written content from upcoming
books. The chapters come straight from our respected authors, before they’re
fully polished and debugged—for critical insights now, when you need them.
This document contains one or more portions of a preliminary version of a Microsoft Press title and is provided
“as is.” The content may be changed substantially upon final publication. In addition, this document may make
reference to pre-released versions of software products that may be changed substantially prior to final
commercial release. Microsoft reserves the right to not publish this title or any versions thereof (including
future prePress ebooks). This document is provided for informational purposes only. MICROSOFT MAKES NO
WARRANTIES, EITHER EXPRESS OR IMPLIED, IN THIS DOCUMENT. Information and views expressed in this
document, including URL and other Internet website references may be subject to change without notice. You
bear the risk of using it.
The document discusses and compares two popular ActionScript frameworks: PureMVC and Robotlegs. It provides an overview of why frameworks are used, describes some common design patterns implemented in frameworks, and highlights key features and strengths/weaknesses of PureMVC and Robotlegs.
An introduction to Typescript for programmers who use JavaScript.
It goes through what it is, what's it useful for, how to start using it and some things I've observed while using it.
Notes are not available but feel free to PM me if you have any question.
This document summarizes a thesis about automatically deriving semantic properties from source code. It introduces the Compose .NET project, which uses aspect-oriented programming to add features to .NET languages. The thesis aims to enhance Compose by extracting more semantic information from code. It presents the Semantic Analyzer, which parses code into a metamodel representing semantic actions. This metamodel can then be queried to provide semantic properties for tasks like pointcut matching and program analysis.
.NET is designed to solve problems that have plagued programmers in the past like incompatibilities between programming languages and technologies. It provides a common language runtime and type system that allows different languages to work together. The .NET Framework handles many common programming tasks like serialization automatically through metadata and provides a large class library for common functions.
The Architecture Of Software Defined Radios EssayDivya Watson
This project aims to build a smart assistant to help users purchase books online by integrating
multiple sources of information about books and the purchasing process into a single system. By
consolidating data from sources about books, reviews, prices and retailers, the assistant can provide
users all the necessary information to make an informed purchase decision in one place. The goal is
to streamline the online book buying experience for users by eliminating the need to search across
multiple websites during the purchase process.
This document discusses the implementation of an API for the Auphonic audio post-production web service. It covers the design and technologies used, including libraries like Django and Piston. Authentication methods like OAuth and HTTP Basic are also covered. The implementation of the Auphonic API and details of its features for audio productions and presets are then described. The goal was to create a scalable API that allows users to automate tasks and integrate Auphonic into other systems.
This document discusses principles for writing clean infrastructure as code. It advocates applying principles of clean code and software architecture to infrastructure code. Common tools and approaches like Docker, Kubernetes, Terraform and Pulumi are mentioned. Specific principles discussed include KISS, DRY, separation of concerns, and following conventions for naming, modularity, and testability. Examples of declarative and imperative infrastructure code in Pulumi are also provided.
This document discusses the installation and use of ANTLR, a parser generator tool. It begins with steps to install ANTLR and Java on a Windows system. It then provides an example of running ANTLR on a C++ grammar file to generate lexer and parser files in C#. The document explains that ANTLR automatically generates lexical and syntax analyzers from grammar files written in ANTLR's grammar language. It also discusses using the generated listener and visitor classes to traverse the parse tree.
Most dev teams have a very simple conception of software architecture. They start with a database, a user interface, and add layers of (DRY) mess between the two. Then they have a performance problem so they add memcache and mongodb (Now we're webscale!).
Months or years later, releasing new features in production gets harder and riskier: it's time for a rewrite. Let's use AnguNodeMvcDoop to solve all our maintainability issues! And the cycle starts over...
In this talk we'll see that software architecture is not defined by the technologies you use but by the high level principles you set. We'll see what really matters to make your information system maintainable and how to get there progressively!
How do we document code? A good solution is to create self-explanatory code; this somewhat eliminates the need to document the code. We still need some very basic documentation. Code comments are one form of documentation, that is often misused. This talk is about self-explanatory code, the documentation we need and code comment patterns and anti-patterns.
This document provides an overview of sockets programming in Python. It discusses the basic Python sockets modules, including the Socket module which provides a low-level networking interface based on the BSD sockets API, and the SocketServer module which simplifies the development of network servers. It also provides examples of creating server and client sockets in Python and performing basic I/O operations. The document demonstrates how to create TCP and UDP sockets, bind addresses, listen for connections, accept clients, and send/receive data.
The document discusses the seven pillars of ASP.NET that differentiate it from previous web development platforms. These pillars include: 1) ASP.NET being integrated with the .NET Framework; 2) ASP.NET being compiled rather than interpreted; 3) ASP.NET being multilanguage; 4) ASP.NET being hosted by the Common Language Runtime; 5) ASP.NET being object-oriented; and 6) ASP.NET supporting all browsers. The document provides details on each pillar to explain the advantages ASP.NET provides to web developers.
Atmel - Next-Generation IDE: Maximizing IP Reuse [WHITE PAPER]Atmel Corporation
Atmel® Studio 6 is the integrated development platform (IDP) for developing and debugging Atmel ARM® Cortex™-M and Atmel AVR® microcontroller- (MCU-) based applications. The Atmel Studio 6 IDP gives you a seamless and easy-to-use environment to write, build and debug your applications written in C/C++ or assembly code.
Atmel Studio 6 is free of charge and is integrated with the Atmel Software Framework (ASF)—a large library of free source code with 1,600 ARM and AVR project examples. ASF strengthens the IDP by providing, in the same environment, access to ready-to-use code that minimizes much of the low-level design required for projects. Use the IDP for our wide variety of AVR and ARM Cortex-M processor-based MCUs, including our broadened portfolio of Atmel SAM3 ARM Cortex-M3 and M4 Flash devices.
With the introduction of Atmel Gallery and Atmel Spaces, Atmel Studio 6 further simplifies embedded MCU designs to reduce development time and cost. Atmel Gallery is an online apps store for development tools and embedded software. Atmel Spaces is a cloud-based collaborative development workspace allowing you to host software and hardware projects targeting Atmel MCUs.
For more information, please visit http://www.atmel.com/Microsite/atmel_studio6.
Follow along on Twitter at http://www.twitter.com/Atmel and 'Like' Atmel on Facebook at http://www.facebook.com/atmelcorporation.
ContainerDayVietnam2016: Become a Cloud-native DeveloperDocker-Hanoi
Container design patterns are emerging as microservices and containerization become more popular. Single-container patterns like container boundary and interface define how containers are packaged and interact. Single-node patterns like Kubernetes pods and sidecars schedule related containers together on one machine. Multi-node patterns coordinate distributed containers, such as using leader election sidecars to select a replication leader, work queues to distribute tasks, and scatter/gather to parallelize computations across nodes. These patterns abstract away infrastructure details and provide reusable solutions for containerized applications.
The document discusses the seven pillars of ASP.NET that differentiated it from previous web development platforms when it was first released. These pillars include: 1) ASP.NET being integrated with the .NET Framework; 2) ASP.NET applications being compiled instead of interpreted; 3) ASP.NET being multilanguage; 4) ASP.NET being hosted by the Common Language Runtime; 5) ASP.NET being object-oriented; 6) ASP.NET supporting all browsers; and 7) ASP.NET having a stateful programming model.
Driving Business Innovation: Latest Generative AI Advancements & Success StorySafe Software
Are you ready to revolutionize how you handle data? Join us for a webinar where we’ll bring you up to speed with the latest advancements in Generative AI technology and discover how leveraging FME with tools from giants like Google Gemini, Amazon, and Microsoft OpenAI can supercharge your workflow efficiency.
During the hour, we’ll take you through:
Guest Speaker Segment with Hannah Barrington: Dive into the world of dynamic real estate marketing with Hannah, the Marketing Manager at Workspace Group. Hear firsthand how their team generates engaging descriptions for thousands of office units by integrating diverse data sources—from PDF floorplans to web pages—using FME transformers, like OpenAIVisionConnector and AnthropicVisionConnector. This use case will show you how GenAI can streamline content creation for marketing across the board.
Ollama Use Case: Learn how Scenario Specialist Dmitri Bagh has utilized Ollama within FME to input data, create custom models, and enhance security protocols. This segment will include demos to illustrate the full capabilities of FME in AI-driven processes.
Custom AI Models: Discover how to leverage FME to build personalized AI models using your data. Whether it’s populating a model with local data for added security or integrating public AI tools, find out how FME facilitates a versatile and secure approach to AI.
We’ll wrap up with a live Q&A session where you can engage with our experts on your specific use cases, and learn more about optimizing your data workflows with AI.
This webinar is ideal for professionals seeking to harness the power of AI within their data management systems while ensuring high levels of customization and security. Whether you're a novice or an expert, gain actionable insights and strategies to elevate your data processes. Join us to see how FME and AI can revolutionize how you work with data!
Let's Integrate MuleSoft RPA, COMPOSER, APM with AWS IDP along with Slackshyamraj55
Discover the seamless integration of RPA (Robotic Process Automation), COMPOSER, and APM with AWS IDP enhanced with Slack notifications. Explore how these technologies converge to streamline workflows, optimize performance, and ensure secure access, all while leveraging the power of AWS IDP and real-time communication via Slack notifications.
Project Management Semester Long Project - Acuityjpupo2018
Acuity is an innovative learning app designed to transform the way you engage with knowledge. Powered by AI technology, Acuity takes complex topics and distills them into concise, interactive summaries that are easy to read & understand. Whether you're exploring the depths of quantum mechanics or seeking insight into historical events, Acuity provides the key information you need without the burden of lengthy texts.
Cosa hanno in comune un mattoncino Lego e la backdoor XZ?Speck&Tech
ABSTRACT: A prima vista, un mattoncino Lego e la backdoor XZ potrebbero avere in comune il fatto di essere entrambi blocchi di costruzione, o dipendenze di progetti creativi e software. La realtà è che un mattoncino Lego e il caso della backdoor XZ hanno molto di più di tutto ciò in comune.
Partecipate alla presentazione per immergervi in una storia di interoperabilità, standard e formati aperti, per poi discutere del ruolo importante che i contributori hanno in una comunità open source sostenibile.
BIO: Sostenitrice del software libero e dei formati standard e aperti. È stata un membro attivo dei progetti Fedora e openSUSE e ha co-fondato l'Associazione LibreItalia dove è stata coinvolta in diversi eventi, migrazioni e formazione relativi a LibreOffice. In precedenza ha lavorato a migrazioni e corsi di formazione su LibreOffice per diverse amministrazioni pubbliche e privati. Da gennaio 2020 lavora in SUSE come Software Release Engineer per Uyuni e SUSE Manager e quando non segue la sua passione per i computer e per Geeko coltiva la sua curiosità per l'astronomia (da cui deriva il suo nickname deneb_alpha).
Fueling AI with Great Data with Airbyte WebinarZilliz
This talk will focus on how to collect data from a variety of sources, leveraging this data for RAG and other GenAI use cases, and finally charting your course to productionalization.
UiPath Test Automation using UiPath Test Suite series, part 6DianaGray10
Welcome to UiPath Test Automation using UiPath Test Suite series part 6. In this session, we will cover Test Automation with generative AI and Open AI.
UiPath Test Automation with generative AI and Open AI webinar offers an in-depth exploration of leveraging cutting-edge technologies for test automation within the UiPath platform. Attendees will delve into the integration of generative AI, a test automation solution, with Open AI advanced natural language processing capabilities.
Throughout the session, participants will discover how this synergy empowers testers to automate repetitive tasks, enhance testing accuracy, and expedite the software testing life cycle. Topics covered include the seamless integration process, practical use cases, and the benefits of harnessing AI-driven automation for UiPath testing initiatives. By attending this webinar, testers, and automation professionals can gain valuable insights into harnessing the power of AI to optimize their test automation workflows within the UiPath ecosystem, ultimately driving efficiency and quality in software development processes.
What will you get from this session?
1. Insights into integrating generative AI.
2. Understanding how this integration enhances test automation within the UiPath platform
3. Practical demonstrations
4. Exploration of real-world use cases illustrating the benefits of AI-driven test automation for UiPath
Topics covered:
What is generative AI
Test Automation with generative AI and Open AI.
UiPath integration with generative AI
Speaker:
Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP
In the rapidly evolving landscape of technologies, XML continues to play a vital role in structuring, storing, and transporting data across diverse systems. The recent advancements in artificial intelligence (AI) present new methodologies for enhancing XML development workflows, introducing efficiency, automation, and intelligent capabilities. This presentation will outline the scope and perspective of utilizing AI in XML development. The potential benefits and the possible pitfalls will be highlighted, providing a balanced view of the subject.
We will explore the capabilities of AI in understanding XML markup languages and autonomously creating structured XML content. Additionally, we will examine the capacity of AI to enrich plain text with appropriate XML markup. Practical examples and methodological guidelines will be provided to elucidate how AI can be effectively prompted to interpret and generate accurate XML markup.
Further emphasis will be placed on the role of AI in developing XSLT, or schemas such as XSD and Schematron. We will address the techniques and strategies adopted to create prompts for generating code, explaining code, or refactoring the code, and the results achieved.
The discussion will extend to how AI can be used to transform XML content. In particular, the focus will be on the use of AI XPath extension functions in XSLT, Schematron, Schematron Quick Fixes, or for XML content refactoring.
The presentation aims to deliver a comprehensive overview of AI usage in XML development, providing attendees with the necessary knowledge to make informed decisions. Whether you’re at the early stages of adopting AI or considering integrating it in advanced XML development, this presentation will cover all levels of expertise.
By highlighting the potential advantages and challenges of integrating AI with XML development tools and languages, the presentation seeks to inspire thoughtful conversation around the future of XML development. We’ll not only delve into the technical aspects of AI-powered XML development but also discuss practical implications and possible future directions.
Introduction of Cybersecurity with OSS at Code Europe 2024Hiroshi SHIBATA
I develop the Ruby programming language, RubyGems, and Bundler, which are package managers for Ruby. Today, I will introduce how to enhance the security of your application using open-source software (OSS) examples from Ruby and RubyGems.
The first topic is CVE (Common Vulnerabilities and Exposures). I have published CVEs many times. But what exactly is a CVE? I'll provide a basic understanding of CVEs and explain how to detect and handle vulnerabilities in OSS.
Next, let's discuss package managers. Package managers play a critical role in the OSS ecosystem. I'll explain how to manage library dependencies in your application.
I'll share insights into how the Ruby and RubyGems core team works to keep our ecosystem safe. By the end of this talk, you'll have a better understanding of how to safeguard your code.
How to Get CNIC Information System with Paksim Ga.pptxdanishmna97
Pakdata Cf is a groundbreaking system designed to streamline and facilitate access to CNIC information. This innovative platform leverages advanced technology to provide users with efficient and secure access to their CNIC details.
For the full video of this presentation, please visit: https://www.edge-ai-vision.com/2024/06/building-and-scaling-ai-applications-with-the-nx-ai-manager-a-presentation-from-network-optix/
Robin van Emden, Senior Director of Data Science at Network Optix, presents the “Building and Scaling AI Applications with the Nx AI Manager,” tutorial at the May 2024 Embedded Vision Summit.
In this presentation, van Emden covers the basics of scaling edge AI solutions using the Nx tool kit. He emphasizes the process of developing AI models and deploying them globally. He also showcases the conversion of AI models and the creation of effective edge AI pipelines, with a focus on pre-processing, model conversion, selecting the appropriate inference engine for the target hardware and post-processing.
van Emden shows how Nx can simplify the developer’s life and facilitate a rapid transition from concept to production-ready applications.He provides valuable insights into developing scalable and efficient edge AI solutions, with a strong focus on practical implementation.
HCL Notes and Domino License Cost Reduction in the World of DLAUpanagenda
Webinar Recording: https://www.panagenda.com/webinars/hcl-notes-and-domino-license-cost-reduction-in-the-world-of-dlau/
The introduction of DLAU and the CCB & CCX licensing model caused quite a stir in the HCL community. As a Notes and Domino customer, you may have faced challenges with unexpected user counts and license costs. You probably have questions on how this new licensing approach works and how to benefit from it. Most importantly, you likely have budget constraints and want to save money where possible. Don’t worry, we can help with all of this!
We’ll show you how to fix common misconfigurations that cause higher-than-expected user counts, and how to identify accounts which you can deactivate to save money. There are also frequent patterns that can cause unnecessary cost, like using a person document instead of a mail-in for shared mailboxes. We’ll provide examples and solutions for those as well. And naturally we’ll explain the new licensing model.
Join HCL Ambassador Marc Thomas in this webinar with a special guest appearance from Franz Walder. It will give you the tools and know-how to stay on top of what is going on with Domino licensing. You will be able lower your cost through an optimized configuration and keep it low going forward.
These topics will be covered
- Reducing license cost by finding and fixing misconfigurations and superfluous accounts
- How do CCB and CCX licenses really work?
- Understanding the DLAU tool and how to best utilize it
- Tips for common problem areas, like team mailboxes, functional/test users, etc
- Practical examples and best practices to implement right away
Skybuffer SAM4U tool for SAP license adoptionTatiana Kojar
Manage and optimize your license adoption and consumption with SAM4U, an SAP free customer software asset management tool.
SAM4U, an SAP complimentary software asset management tool for customers, delivers a detailed and well-structured overview of license inventory and usage with a user-friendly interface. We offer a hosted, cost-effective, and performance-optimized SAM4U setup in the Skybuffer Cloud environment. You retain ownership of the system and data, while we manage the ABAP 7.58 infrastructure, ensuring fixed Total Cost of Ownership (TCO) and exceptional services through the SAP Fiori interface.
Have you ever been confused by the myriad of choices offered by AWS for hosting a website or an API?
Lambda, Elastic Beanstalk, Lightsail, Amplify, S3 (and more!) can each host websites + APIs. But which one should we choose?
Which one is cheapest? Which one is fastest? Which one will scale to meet our needs?
Join me in this session as we dive into each AWS hosting service to determine which one is best for your scenario and explain why!
Webinar: Designing a schema for a Data WarehouseFederico Razzoli
Are you new to data warehouses (DWH)? Do you need to check whether your data warehouse follows the best practices for a good design? In both cases, this webinar is for you.
A data warehouse is a central relational database that contains all measurements about a business or an organisation. This data comes from a variety of heterogeneous data sources, which includes databases of any type that back the applications used by the company, data files exported by some applications, or APIs provided by internal or external services.
But designing a data warehouse correctly is a hard task, which requires gathering information about the business processes that need to be analysed in the first place. These processes must be translated into so-called star schemas, which means, denormalised databases where each table represents a dimension or facts.
We will discuss these topics:
- How to gather information about a business;
- Understanding dictionaries and how to identify business entities;
- Dimensions and facts;
- Setting a table granularity;
- Types of facts;
- Types of dimensions;
- Snowflakes and how to avoid them;
- Expanding existing dimensions and facts.
Ocean lotus Threat actors project by John Sitima 2024 (1).pptxSitimaJohn
Ocean Lotus cyber threat actors represent a sophisticated, persistent, and politically motivated group that poses a significant risk to organizations and individuals in the Southeast Asian region. Their continuous evolution and adaptability underscore the need for robust cybersecurity measures and international cooperation to identify and mitigate the threats posed by such advanced persistent threat groups.
AI 101: An Introduction to the Basics and Impact of Artificial IntelligenceIndexBug
Imagine a world where machines not only perform tasks but also learn, adapt, and make decisions. This is the promise of Artificial Intelligence (AI), a technology that's not just enhancing our lives but revolutionizing entire industries.
Main news related to the CCS TSI 2023 (2023/1695)Jakub Marek
An English 🇬🇧 translation of a presentation to the speech I gave about the main changes brought by CCS TSI 2023 at the biggest Czech conference on Communications and signalling systems on Railways, which was held in Clarion Hotel Olomouc from 7th to 9th November 2023 (konferenceszt.cz). Attended by around 500 participants and 200 on-line followers.
The original Czech 🇨🇿 version of the presentation can be found here: https://www.slideshare.net/slideshow/hlavni-novinky-souvisejici-s-ccs-tsi-2023-2023-1695/269688092 .
The videorecording (in Czech) from the presentation is available here: https://youtu.be/WzjJWm4IyPk?si=SImb06tuXGb30BEH .
5. Chapter 1
Introduction
An application programming interface, or API, is the set of symbols that are
exported and available to the users of a library to write their applications.
The design of the APIs is arguably the most critical part of designing the
library, because it affects the design of the applications built on top of them.
To quote Daniel Jackson1:
Software is built on abstractions. Pick the right ones, and pro-
gramming will flow naturally from design; modules will have
small and simple interfaces; and new functionality will more
likely fit in without extensive reorganization. Pick the wrong
ones, and programming will be a series of nasty surprises.
This manual gathers together the key insights into API design that were
discovered through many years of software development on the Qt appli-
cation development framework at Trolltech (now part of Nokia). When
designing and implementing a library, you should also keep other factors
in mind, such as efficiency and ease of implementation, in addition to pure
API considerations. And although the focus is on public APIs, there is no
harm in applying the principles described here when writing application
code or internal library code.
Qt! Examples from Qt’s history are presented in blocks like this one. If you are
new to Qt, you might find some of these examples obscure. Don’t hesitate
to ask your colleagues for details. Also, many of the examples come from
classes on which I worked, for the simple reason that I know those best.
Other classes could have provided just as good examples.
Acknowledgment. My first acknowledgment is of Lars Knoll, who en-
couraged me to write this manual and gave feedback during the writing.
I would also like to thank Frans Englich, Andreas Aardal Hanssen, Simon
1Daniel Jackson, Software Abstractions, MIT Press, 2006.
5
6. Hausmann, Mark Summerfield, Jan-Arve Sæther, and Trenton W. Schulz
for reviewing manuscripts of this manual, and all the Trolltech developers
with whom I have had fruitful API discussions.
6
7. Chapter 2
Characteristics of Good APIs
What is a good API? Although the concept is inherently subjective, most
library developers seem to agree on the main desirable characteristics of an
API. The list below is inspired by a talk by Joshua Bloch1 and an article by
Matthias Ettrich2:
• Easy to learn and memorize
• Leads to readable code
• Hard to misuse
• Easy to extend
• Complete
Observe that “minimal” and “consistent” don’t appear on the list. They
don’t need to; a bloated, inconsistent API will be hard to learn and mem-
orize, and also hard to extend. We should strive for minimality and con-
sistency, but only to the extent that they contribute to meeting the criteria
listed above.
“Consistency” coincides broadly with “conceptual integrity”, the prin-
ciple that a complex system should have a coherent design, reflecting the
vision of one architect. Decades ago, Frederick Brooke wrote3:
I contend that conceptual integrity is the most important con-
sideration in system design. It is better to have a system omit
certain anomalous features and improvements, but to reflect
one set of design ideas, than to have one that contains many
good but independent and uncoordinated ideas.
1Joshua Bloch, “How to Design a Good API and Why It Matters”, Google Tech Talk, 2007.
Available at http://video.google.com/videoplay?docid=-3733345136856180693.
2Matthias Ettrich, “Designing Qt-Style C++ APIs”, Qt Quarterly 13, 2004. Available at
http://doc.trolltech.com/qq/qq13-apis.html.
3Frederick P. Brooks, Jr., The Mythical Man-Month: Essays on Software Engineering,
Addison-Wesley, 1975. Second edition 1995.
7
8. Incidentally, if you are lucky enough to be extending a library that al-
ready exhibits the virtues listed above, mimicry is your fast track to success.
2.1 Easy to learn and memorize
An easy-to-learn API features consistent naming conventions and patterns,
economy of concepts, and predictability. It uses the same name for the same
concept, and different names for different concepts.
A minimal API is easy to memorize because there is little to remember.
A consistent API is easy to memorize because you can reapply what you
learned in one part of the API when using a different part.
An API is not only the names of the classes and methods that compose
it, but also their intended semantics. The semantics should be simple and
clear, and follow the principle of least surprise.
Some APIs are difficult to learn because they require the user to write
heaps of boilerplate code just to get started. Nothing is more intimidating
to the novice user than creating their first widget, 3D scene, or data model;
and nothing is more destructive to their self-confidence than failing at that.
An easy-to-learn API makes it possible to write the “hello world” example
in just a few easy lines of code and to expand it incrementally to obtain
more complex programs.
Qt! QPushButton is an example of a low-threshold class. You simply instantiate
it and call show() on it, and behold, you have a QPushButton with its own
window frame and taskbar entry. In retrospect, it would be even better if
the call to show() could be omitted (e.g., by showing the widget in the next
iteration of the event loop), and if the QApplication object was implicitly
created by Qt. “Hello world” would then be
#include <QtGui>
int main()
{
QPushButton button("Hello world");
return QApplication::run();
}
Convenience methods—methods that are (or could be) implemented in
terms of other public methods to make certain idioms shorter to write—
contribute to API bloat. However, they are acceptable and indeed encour-
aged so long as they are clearly documented as “convenience” and fit nicely
with the rest of the API. For example, if you provide an insertItem(int,
Item) method that takes an index and an item, it often makes sense to also
provide addItem(Item) as a convenience.
8
9. 2.2 Leads to readable code
A programming language or library can be easy to learn and memorize,
and yet lead to totally opaque code. The language APL is an extreme case;
the expression (˜R∈R◦.×R)/R←1↓ιR returns a list of prime numbers up
to R.4 Closer to us, Perl acquired the reputation of being a “write-only
language” because of its cryptic syntax.
Application code is written only once, but read over and over again
by different developers over the lifetime of the application. Readable code
is easier to document and maintain. It is also less likely to contain bugs,
because the bugs are made more visible by the code’s readability.
Qt! In Qt 3, QSlider’s constructor let you specify various properties:
slider = new QSlider(8, 128, 1, 6, Qt::Vertical, 0,
"volume");
In Qt 4, you would write
slider = new QSlider(Qt::Vertical);
slider->setRange(8, 128);
slider->setValue(6);
slider->setObjectName("volume");
which is easier to read, and even easier to write with no documentation or
autocompletion. It is also easier to see that the value of 6 lies outside the
range [8, 128].
Readable code can be concise or verbose. Either way, it is always at the
right level of abstraction—neither hiding important things nor forcing the
programmer to specify irrelevant information.
Qt! The Qt Jambi code
QGridLayout layout = new QGridLayout;
layout.addWidget(slider, 0, 0);
layout.addWidget(spinBox, 0, 1);
layout.addWidget(resetButton, 2, 1);
layout.setRowStretch(1, 1);
setLayout(layout);
is more readable than the equivalent Swing code:
GridBagLayout layout = new GridBagLayout();
GridBagConstraints constraint = new GridBagConstraints();
constraint.fill = GridBagConstraints.HORIZONTAL;
constraint.insets = new Insets(10, 10, 10, 0);
constraint.weightx = 1;
4Wikipedia, “APL programming language”. Available at http://en.wikipedia.org/
wiki/APL_programming_language.
9
10. layout.setConstraints(slider, constraint);
constraint.gridwidth = GridBagConstraints.REMAINDER;
constraint.insets = new Insets(10, 5, 10, 10);
constraint.weightx = 0;
layout.setConstraints(spinner, constraint);
constraint.anchor = GridBagConstraints.SOUTHEAST;
constraint.fill = GridBagConstraints.REMAINDER;
constraint.insets = new Insets(10, 10, 10, 10);
constraint.weighty = 1;
layout.setConstraints(resetButton, constraint);
JPanel panel = new JPanel(layout);
panel.add(slider);
panel.add(spinner);
panel.add(resetButton);
2.3 Hard to misuse
A well-designed API makes it easier to write correct code than incorrect
code, and encourages good programming practices. It does not needlessly
force the user to call methods in a strict order or to be aware of implicit side
effects or semantic oddities.
To illustrate this point, let us temporarily leave the world of APIs to
consider the syntax of HTML, plain TEX, and LATEX. The table below shows
a short example using all three markup languages:
Result: the goto label statement
HTML: the <b>goto <u>label</u></b> statement
Plain TEX: the {bf goto underline{label}} statement
LATEX: the textbf{goto underline{label}} statement
Because HTML forces us to repeat the name of the tag in the close tag, it
encourages us to write things like
the <b>goto <u>label</b></u> statement
which is badly nested and illegal. Plain TEX doesn’t suffer from this prob-
lem, but it has its own flaws. Many TEX users, including the author of this
document, often find themselves typing things like
the bf{goto underline{label}} statement
which results in “the goto label statement”, i.e., the word “statement”, and
everything that follows until the next right brace, is in boldface. (This is
because the bf command applies to the current scope, while underline’s
10
11. effect is restricted to its {}-delimited argument.) Another plain TEX oddity
is that bold and italic are mutually exclusive. Thus,
the {bf goto {it label/}} statement
produces “the goto label statement”. A third quirk is that we must remem-
ber to insert the italic correction kerning (/) after the italicized text. LATEX
solves all these problems, at the cost of introducing longer command names
(textbf, textit, etc.).5
API design is, in many ways, like markup language design. An API is
a language, or rather an extension to the programming language. The C++
code below mirrors the HTML example and its flaws:
stream.writeCharacters("the ");
stream.writeStartElement("b");
stream.writeCharacters("goto ");
stream.writeStartElement("i");
stream.writeCharacters("label");
stream.writeEndElement("i");
stream.writeEndElement("b");
stream.writeCharacters(" statement");
Wouldn’t it be nice if we could let the C++ compiler detect bad nesting?
Using the power of expressions, this can be done as follows:
stream.write(Text("the ")
+ Element("b",
Text("goto ")
+ Element("u", "label"))
+ Text(" statement"));
Although the above code snippets are concerned with markup text genera-
tion, the same issues occur in other contexts, say, configuration files, where
settings may be nested in groups:
QSettings settings;
settings.beginGroup("mainwindow");
settings.setValue("size", win->size());
settings.setValue("fullScreen", win->isFullScreen());
settings.endGroup();
There is another lesson to be drawn from markup languages, specifi-
cally HTML. The authors of HTML would like us to use <em> (emphasis)
5A reader commented: “This example is odd. I actually find HTML easier to read than
TEX/LATEX.” Maybe so. But this section is titled “Hard to misuse”, not “Leads to readable
code”.
11
12. instead of <i> and <strong> instead of <b>. However, the frowned-upon
<i> and <b> tags are more convenient to type, and have a clearer seman-
tics (does emphasis mean italic or bold?). If they had been serious about it,
they would have replaced <i> with <font style="italic"> and likewise
for bold, or omitted the tags altogether.
Qt! A common trap in Qt 3 was to swap the initial text and the parent of a
QPushButton, QLabel, or QLineEdit when creating the object. For example:
button = new QPushButton(this, "Hello world");
The code compiled, but the widget didn’t show any text, because “Hello
world” was taken to be the object’s name. In Qt 4, this is caught at compile-
time. If you want to specify an object name, you must write
button = new QPushButton(this);
button->setObjectName("Hello world");
which is very explicit about your intentions.
Finally, we can often make an API hard to misuse by eliminating redun-
dancy. For example, an addItem(Item) method that lets the user write
obj.addItem(yksi);
obj.addItem(kaksi);
obj.addItem(kolme);
is harder to misuse than the more general insertItem(int,Item) method,
which encourages off-by-one errors:
// WRONG
obj.insertItem(0, yksi);
obj.insertItem(1, kaksi);
obj.insertItem(3, kolme);
2.4 Easy to extend
Libraries grow over time. New classes appear. Existing classes get new
methods, methods get new parameters, and enums get new enum values.
APIs should be designed with this in mind. The larger the API, the more
likely the clashes between the new concepts and the existing concepts. In
addition, binary compatibility concerns must be taken into consideration
during the original design phase.
Qt! QStyle is a good example of a class that was difficult to extend in a bi-
nary compatible way in Qt 2. It had a whole series of virtual functions for
painting the different widgets in Qt, which made it impossible to style new
widgets (e.g., QToolBox) without breaking binary compatibility. In Qt 3,
12
13. QStyle’s API was redesigned to be enum-based, so that new widgets could
be supported by adding enum values.
2.5 Complete
Ideally, an API should be complete and let users do everything they want.
It is rarely (if ever) possible to provide a complete API for anything, but at
least it should be possible for users to extend or customize the existing API
(e.g., by subclassing).
Completeness is also something that can appear over time, by incre-
mentally adding functionality to existing APIs. However, it usually helps
even in those cases to have a clear idea of the direction for future develop-
ments, so that each addition is a step in the right direction.
13
15. Chapter 3
The Design Process
APIs are usually the result of a design process that spans several years and
involves many people. Every step in the process offers the opportunity
to improve the API—or to spoil it. This chapter provides some guidance
for designing a new API or extending an existing API. By following these
guidelines, you increase your chances that the API will be a success rather
than a liability.
3.1 Know the requirements
Before you set out to design or implement an API, you should have a good
idea of the requirements. Sometimes, the requirements are reasonably clear
(e.g., “implement POSIX”), but in most cases you will need to conduct some
sort of requirements analysis. A good starting point is to ask as many peo-
ple as possible (notably your boss, your colleagues, and potential users)
about what features they would like to see.
Qt! When designing the new MDI classes for Qt 4.3, the main implementor
wrote an email to the internal developers’ mailing list where he asked about
known issues with the previous MDI framework and any wishes for the
new framework. Beyond helping define the API and feature set, this en-
sured that the other developers had their say and prevented dissension later
on.
3.2 Write use cases before you write any other code
A common mistake when writing library components is to start by im-
plementing the functionality, then design the API, and finally release it.
APIs designed this way tend to reflect the structure of the underlying code,
rather than what the application programmer who will use the API wants
15
16. to write. The implementation should adapt to the user, not the other way
around.
Before you code an implementation or even design an API, start by
writing a few typical application code snippets based on your requirement
list. Don’t worry at this stage about difficulties that would arise in imple-
menting the API. As you write the code snippets, the API takes shape. The
snippets should reflect the Perl motto “Make easy things easy and hard
things possible”.
Qt! For QWizard, the two main scenarios identified were linear wizards and
complex wizards. In a linear wizard, the pages are shown sequentially, and
no pages are ever skipped; in a complex wizard, different traversal paths
are possible depending on user input, describing a directed acyclic graph.
While the linear case can be seen as a special case of the complex case, it is
common enough to deserve particular consideration.
3.3 Look for similar APIs in the same library
When designing a class called XmlQuery, look at the existing SqlQuery
from the same class library. Chances are that they have similar concepts—
you execute or precompile a query, navigate the result set, bind values to
placeholders, and so on. Users who already know SqlQuery can then learn
XmlQuery with very little effort. Furthermore, by mimicking an existing
API, you implicitly benefit from all the incremental design work that went
into that API and the feedback it received.
Of course, it would be foolish to blindly follow an existing API simply
because it is there. Most existing APIs could do with some improvements,
and being entirely consistent with them could turn out to be a two-edged
sword. This having been said, an excellent way to achieve consistency with
a bad API is to fix that API once and for all, and then mimic it.
Finding similar APIs in a large library is not always as easy as in the
XmlQuery/SqlQuery case above. It requires patience, curiosity, and a pow-
erful search tool such as grep.
If you are writing a new version of an API, you should know the API
you are replacing like the back of your hand—otherwise, you will end up
substituting new design flaws for old flaws. It might be tempting to be-
lieve that the old API is “utter crap” and doesn’t deserve your time, but it
is unlikely that it was all wrong, so try to take any good ideas on board.
Moreover, since users will need to port code written for the old API, avoid
gratuitous changes and support a superset of the old functionality.
Qt! Examples of dubious changes in Qt 4.0: QDockWindow was renamed QDock-
Widget (even though everybody says “dock window”) and QTextEdit::
setOverwriteMode() was removed, only to reappear in Qt 4.1.
16
17. 3.4 Define the API before you implement it
For the same reason that you should write code snippets against an API
before you define the API, you should specify the API and its semantics
before you implement it. For a library with thousands of users, it is much
better if the implementation is tricky and the API is straightforward than
than the other way around.
Qt! Qt 4 lets the user specify the parent of a QWidget at any point by calling
setParent(). In Qt 4.0 and 4.1, creating a parentless widget resulted in the
creation of a window behind the scenes, which was very expensive. De-
layed window creation, as introduced in Qt 4.2, is a beautiful example of an
API-driven change to the implementation.
In contrast, the Qt 3 method QWidget::recreate() embodies the evils
of implementation-driven APIs. Granted, on most platforms, QWidget cre-
ated a native widget or window and wrapped it, but this implementation
detail never belonged in the API.
The API and its semantics are the primary product that a library de-
livers. Experience has shown time and time again that APIs outlast their
implementations (e.g., UNIX/POSIX, OpenGL, and QFileDialog).
As you implement the API or write unit tests for your implementation,
you will most probably find flaws or undefined corner cases in your origi-
nal design. Use this opportunity to refine your design, but don’t let imple-
mentation considerations leak into the API, apart in exceptional cases (e.g.,
optimization options).
Qt! QGraphicsScene::setBspTreeDepth() probably constitutes such an ex-
ception. This method lets the user control the depth of the binary space par-
titioning (BSP) tree used to store the items of a graphics scene. QGraphics-
Scene tries to deduce an appropriate tree depth, but if the scene changes
frequently, it may be more efficient to fix the tree depth. The name of the
method is sufficiently intimidating to the user (who might not even know
or care that QGraphicsView uses a BSP tree internally), suggesting that this
is an advanced method.
3.5 Have your peers review your API
Look for feedback. Ask for feedback. Beg for feedback. Show your APIs to
your peers, and collect all the feedback you get. Try to momentarily forget
how much work it would be to implement the requested changes.
When receiving negative feedback, trust the principle that all feedback
is useful. Any opinion (e.g., “This whole thing sucks”, from Joe Blow) is a
new piece of information, which you can recast into a fact and add to your
mental list of facts (e.g., “Joe Blow, a Linux fanatic, strongly dislikes this
17
18. COM-inspired architecture”). The more facts you possess, the better the
chances that you will design a good API.
3.6 Write several examples against the API
After you designed an API, you should write a few examples that use the
API. Often, you can obtain examples simply by fleshing out the use cases
defined earlier. It will also help if other people write examples using the
API and give you their feedback.
Qt! The code snippets that were written initially when experimenting with the
QWizard API eventually became the Class Wizard and the License Wizard
examples provided with Qt, covering among them the linear and complex
cases of a wizard. There is also a Trivial Wizard example, which involves no
subclassing and has a “hello world” flavor.
3.7 Prepare for extensions
Expect your API to be extended in two ways: by the maintainers of the API,
who will add to it (and occasionally deprecate parts of it), and by the users,
who will write subclasses to customize the behavior of its components.
Planning for extensibility requires going through realistic scenarios and
thinking of possible solutions. For each class that declares virtual methods,
you should write at least three subclasses (as examples or as public classes
in the API) to ensure that it is powerful enough to support a wide range of
user requirements. This is sometimes called the rule of three.1
Qt! Qt 4.0 introduced QAbstractSocket, together with the concrete subclasses
QTcpSocket and QUdpSocket. When adding QSslSocket in Qt 4.3, we were
forced to add downcasts in some of QAbstractSocket’s methods, which
should have been virtual but were not. “Manual polymorphism” worked in
this case because QSslSocket lives in the same library as QAbstractSocket,
but it wouldn’t have worked for a third-party component.
3.8 Don’t publish internal APIs without review
Some APIs start their glorious lives as internal APIs before they are made
public. A common mistake is to forget to review them properly before
taking this step. This story from Raymond Chen2 illustrates the point:
1Will Tracz, “Software Reuse”, 1995. Available at http://webcem01.cem.itesm.mx:
8005/web/200111/cb00894/software_reuse.html.
2Raymond Chen, “Why is the function SHStripMneumonic misspelled?”, The Old New
Thing blog, 2008. Available at http://blogs.msdn.com/oldnewthing/archive/2008/
05/19/8518565.aspx.
18
19. If you wander through MSDN, you may stumble across the
function SHStripMneumonic. The correct spelling is mnemonic.
Why is the function name misspelled?
“It was like that when I got here.”
The function was originally written for internal use only, and
the person who wrote the function spelled the word incorrectly.
Still, since it was an internal function, there was no real urgency
to fix it.
[...]
In 2001, the order came down to document all functions which
met specific criteria (the details of which I will not go into, and
I would appreciate it if others didn’t try), and the SHStrip-
Mneumonic function was suddenly thrust onto the public stage
before it had a chance to so much as comb its hair and make
sure it didn’t have food stuck in its teeth. The function had to
be documented, warts and all, and the bad spelling was one of
the warts.
Of course, now that the function has been published, its name
is locked and can’t be changed, because that would break all the
programs that used the original bad spelling.
3.9 When in doubt, leave it out
If you have your doubts about an API or functionality, you can leave it out,
or mark it as internal, and reconsider it at a later point.
It often helps to wait for feedback from users. On the other hand, it is
practically impossible to add every feature suggested by users. A good rule
of thumb is to wait until at least three users have independently asked for
a feature before implementing it.
19
21. Chapter 4
Design Guidelines
The guidelines presented in this chapter aim to help you get your APIs
right. You can refer back to them at various stages of the process high-
lighted in the previous chapter. These guidelines were discovered by see-
ing them broken in actual APIs developed at Trolltech or elsewhere.
For many guidelines, we could formulate an equally true (but less often
violated) counter-guideline. For example, from guideline 4.8, “Avoid mak-
ing your APIs overly clever”, we get the counter-guideline “Avoid making
your APIs overly dumb”, and from guideline 4.9, “Pay attention to edge
cases”, we get the counter-guideline “Focus on the general case”. The need
to consider many conflicting requirements is precisely what makes API de-
sign so rewarding. In the end, guidelines are no substitute for using your
brain.
Naming
4.1 Choose self-explanatory names and signatures
To facilitate reading and writing code, pick names and signatures that are
self-explanatory. The names should read like English.
Qt! QPainterPath’s main author recommended writing “vector path” rather
than “painter path” in the documentation, because “everybody else calls it
a vector path”. Why doesn’t Qt call it QVectorPath then?
Until Qt 4.2, another example was QWorkspace, which implemented
MDI (multiple document interface). Why didn’t MDI appear in the name?
Thankfully, the new class that supersedes it is called QMdiArea.
The meaning of the arguments to a method should be clear from the
context at the call site. Beware of bool parameters, which often lead to
unreadable code.
21
22. Qt! QWidget::repaint() takes an optional bool that controls whether the wid-
get should be erased before it is repainted. Code like repaint(false)
leaves some readers wondering whether the method does anything at all
(“don’t repaint!”). At the very least, the argument should have been an
enum.
Strive for consistency in naming. If you use the terms “widgets” and
“controls” interchangeably, users will be mislead into believing that there
is a difference. And if you use the same term for two distinct concepts,
users will be even more confused, until they read the documentation. Con-
sistency is particularly important when fixing the order of parameters. If
rectangles are described as (x, y, width, height) in one part of the API, they
shouldn’t become (x, width, y, height) elsewhere.
Qt! In the run-up to Qt 4.0, QStackArray implemented a vector stored on the
call stack, much like the C99 variable-length arrays (VLAs). What was
wrong with it? Qt already had a QStack container class, implementing a
FIFO (first in, first out) list. So QStackArray sounded like an array of FIFO
lists to anyone who knew about QStack. To avoid overloading the word
“stack”, we renamed the class QVarLengthArray.
Good naming also requires knowing the audience. If you define a pow-
erful API for XML, you will most certainly need to use XML jargon in the
API names. (You should also define it in the documentation and provide
links into the relevant standards.) If, on the contrary, you are designing a
high-level API for XML, don’t expect your readers to know what IDREFs
and NCNames are.
Giving good parameter names is also part of designing an API, even
in languages like C++ where they are not part of the signature. Parameter
names figure both in the documentation and in the autocompletion tooltips
provided by some development environments. Renaming poorly-named
parameters is tedious and error-prone, so give the same care to parameter
naming as you give to the other aspects of the API. In particular, avoid all
single-letter parameter names.1
4.2 Choose unambiguous names for related things
If two or more similar concepts need to be distinguished, choose names
that map unambiguously to the concepts they denote. More specifically,
given the set of names {n1, . . . , nk} and the set of concepts {c1, . . . , ck}, it
should be easy for anyone to associate the names with the right concepts
without looking them up in the documentation.
1Exceptionally, the names x, y, and z for plane coordinates are invariably superior to
their pedantic cousins abscissa, ordinate, and applicate.
22
23. Suppose you have two event delivery mechanisms, one for immediate
(synchronous) delivery and one for delayed (asynchronous) delivery. The
names sendEventNow() and sendEventLater() suggest themselves. If the
intended audience is expected to know the “synchronous” terminology,
you could also call them sendEventSynchronously() and sendEvent-
Asynchronously().
Now, if you want to encourage your users to use synchronous deliv-
ery (e.g., because it is more lightweight), you could name the synchronous
method sendEvent() and keep sendEventLater() for the asynchronous
case. If you would rather have them use asynchronous delivery (e.g., be-
cause it merges consecutive events of the same type), you could name
the synchronous method sendEventNow() and the asynchronous method
sendEvent() or postEvent().
Qt! In Qt, sendEvent() is synchronous, and postEvent() is asynchronous.
One way to keep them separated is to observe that sending an email is usu-
ally much faster than posting a letter using regular mail. Still, the names
could have been clearer.
A similar principle applies when naming the parameter of a copy con-
structor or of an assignment operator in C++. Because it offers good con-
trast with the implicit this parameter, other is a good name. A poorer
choice would be to call it after the class:
// SUBOPTIMAL
Car &Car::operator=(const Car &car)
{
m_model = car.m_model;
m_year = car.m_year;
m_mileage = car.m_mileage;
...
return *this;
}
What is wrong with this? This method deals with two Cars: *this and car.
The name car is appropriate in contexts where there is only one Car, but it
is not helping much when there are two or more.
4.3 Beware of false consistency
APIs, like good writing, should display symmetry. In his American English
style book2, William Strunk Jr. enjoins us to “express co-ordinate ideas in
2William Strunk Jr., The Elements of Style, 1918. Available online at http://www.
bartleby.com/141/.
23
24. similar form”, adding:
This principle, that of parallel construction, requires that ex-
pressions of similar content and function should be outwardly
similar. The likeness of form enables the reader to recognize
more readily the likeness of content and function. Familiar in-
stances from the Bible are the Ten Commandments, the Beati-
tudes, and the petitions of the Lord’s Prayer.
The flip side of this rule is that asymmetry of function should be re-
flected by asymmetry of form. Consequently, if you make a habit of prefix-
ing setter methods with “set” (e.g., setText()), then avoid that prefix for
methods that aren’t setters.
Qt! This guideline has been violated every so often in Qt’s history. The Qt 3
method QStatusBar::message(text, msecs) displayed a message in the
status bar for a specified amount of milliseconds. The name looks like that
of a getter, even though the method is non-const and returns void. For Qt
4, we considered renaming it setMessage() for “consistency”. However,
with its two parameters, the method doesn’t feel quite like a setter. In the
end, we settled for the name showMessage(), which doesn’t suggest false
analogies.
The event delivery example from the previous guideline can also serve
as illustration here. In C++, since a synchronous mechanism delivers the
event immediately, the event can usually be created on the stack and passed
as a const reference, as follows:
KeyEvent event(KeyPress, key, state);
sendEventNow(event);
In contrast, the asynchronous mechanism requires creating the object using
new, and the object is deleted after it has been delivered:
KeyEvent *event = new KeyEvent(KeyPress, key, state);
sendEventLater(event);
Thanks to static typing, the compiler will catch the following bad idioms:
// WON’T COMPILE
KeyEvent *event = new KeyEvent(KeyPress, key, state);
sendEventNow(event);
// WON’T COMPILE
KeyEvent event(KeyPress, key, state);
sendEventLater(event);
24
25. False consistency would suggest making the two methods’ signatures iden-
tical, despite the asymmetry of function (namely, sendEventLater() takes
ownership of the event, whereas sendEventNow() doesn’t).
Qt! In Qt, we walked straight into the trap: sendEvent() and postEvent()
both take a pointer, which makes it very easy to leak memory or double-
delete the event.
From an API perspective, a better solution would have been to restore
the symmetry by having sendEventNow() take ownership of the event or
sendEventLater() copy it. However, this is less efficient. To attract the
favor of the gods, we must routinely sacrifice pure API design principles
on the altars of performance and ease of implementation.
4.4 Avoid abbreviations
In an API, abbreviations mean that users must remember which words are
abbreviated, and in which contexts. For this reason, they should gener-
ally be avoided. An exception is often made for very common, unambigu-
ous forms such as “min”, “max”, “dir”, “rect”, and “prev”, but then this
convention must be applied consistently; otherwise, users will inadver-
tently invoke setMaximumCost() instead of setMaxCost(), and the day
after they will try to call setMaxWidth() instead of setMaximumWidth().
Although errors like this are caught by the compiler, they can aggravate
users.
Qt! The examples above come straight from Qt 4 (QCache and QWidget). Simi-
larly, Qt 4 has QDir and QFileInfo::isDir() but also QFileDialog::set-
Directory() and QProcess::workingDirectory().
This guideline applies to abbreviations, not to acronyms. To separate
the two, listen in the hallway: XML is called XML, not Extensible Markup
Language, so it qualifies as an acronym; but JavaScript is JavaScript, not JS.
In addition, since users don’t have to type parameter names, abbrevia-
tions are acceptable in that context, so long as their meaning is clear.
4.5 Prefer specific names to general names
Prefer specific names to general ones, even if they sometimes seem too re-
strictive. Remember that names occupy API real estate: Once a name is
taken, it cannot be used for something else. This is especially an issue with
class names, since a library might contain hundreds or even thousands of
classes that need distinct names. Another reason for preferring more spe-
cific names is that they are easier for users to relate to.
25
26. Qt! The QRegExp class provides support for regular expressions, but also for
wildcards and fixed strings. It could also have been called QStringPattern,
but this more general name hides what the class is used for in the vast major-
ity of cases, namely, regular expressions. For this reason, the name QRegExp
is arguably the most appropriate for the class.
If you need an error-reporting mechanism for SQL, call the abstract base
class SqlErrorHandler rather than just ErrorHandler, even if the imple-
mentation is not tied to SQL. Arguably, calling the class ErrorHandler
could facilitate its reuse in other parts of the API, but in practice this kind
of reuse is unlikely, because it is hard to foresee future requirements. Some-
day, you might need an error handling mechanism for XML that is slightly
different from the SQL error handing and call it XmlErrorHandler. Ten
years down the road, you might finally discover a way to unify all error
handlers—then, you will be thankful that the name ErrorHandler is still
available, and use it as a base class for all the specific handler classes in the
next version of the library, when you can break binary compatibility.
Qt! For many years, Qt provided two APIs for XML: SAX and DOM. A nice,
symmetric naming convention would have been to use QSax and QDom as the
class prefixes, but unfortunately we settled for QXml for SAX and QDom for
DOM. The asymmetry, annoying on esthetic grounds, became plain confus-
ing as we introduced new XML classes in Qt 4.3 and 4.4, also with the QXml
prefix. Looking at the class names, nobody call tell that QXmlReader and
QXmlSimpleReader are part of the now semi-deprecated SAX API, whereas
QXmlStreamReader is the preferred Qt approach to parse XML documents.
4.6 Don’t be a slave of an underlying API’s naming
practices
A common requirement is to wrap an existing API or implement a file for-
mat or protocol. These normally come with their own names, which might
be poorly chosen or clash with the names in your library. As a general
rule, don’t hesitate to invent your own terminology. For example, if you to
wrap the OpenGL pbuffer extension in a class, call it GLPixelBuffer, not
GLPbuffer.
Similarly, when porting an API to a new programming language, you
should try to merge it well with your library, rather than subject yourself
to the foreign conventions. The few users who know the existing API in
the other language won’t mind the improvements, whereas the remaining
users will greatly benefit from them.
Qt! The SAX classes in Qt are modeled after the de facto standard SAX API
for Java. Some changes were made to accommodate C++ and Qt, but on
the whole the C++ architecture is very similar to the Java one—much too
26
27. similar, in fact. For example, the XML data is provided by a class called
QXmlInputSource, which can be initialized with a QIODevice; a tighter
integration with Qt would have used QIODevice directly and eliminated
QXmlInputSource.
Semantics
4.7 Choose good defaults
Choose suitable defaults so that users won’t need to write or copy and paste
boilerplate code just to get started. For example, in user interface design, a
good default is to respect the platform’s native look and feel. Using Qt for
Mac OS X, we simply write
QPushButton *button = new QPushButton(text, parent);
and we obtain a native-looking Aqua push button with the specified text
and an appropriate preferred size (its “size hint”), ready to be inserted in
a layout manager. Contrast this with the following code, written using
Apple’s Cocoa framework:
static const NSRect dummyRect = {
{ 0.0, 0.0 }, { 0.0, 0.0 }
};
NSButton *button = [[NSButton alloc]
initWithFrame:dummyRect];
[button setButtonType:NSMomentaryLightButton];
[button setBezelStyle:NSRoundedBezelStyle];
[button setTitle:[NSString stringWithUTF8String:text]];
[parent addSubview:button];
Why do we need to set the button type and the bezel style to get a plain
Aqua button? If compatibility with NeXTstep and OpenStep is that impor-
tant, why not provide a convenience class (NSPushButton or NSRounded-
Button or NSAquaButton, whatever) with the right defaults? And why do
we need to specify a position and a size to the initializer method, when we
probably need to set them later anyway based on the window size and the
button’s reported preferred size?
But choosing good defaults isn’t just about eliminating boilerplate code.
It also helps make the API simple and predictable. This applies especially
to Boolean options. In general, name them so that they are false by default
and enabled by the user. In some cases, this requires prefixing them with No
or Dont or Anti. This is acceptable, although alternatives should be sought
27
28. when possible (e.g., CaseInsensitive rather than NotCaseSensitive). In
all cases, resist the temptation to enable all sorts of bells and whistles by
default just to show off.
Finally, remember that choosing good defaults doesn’t excuse you from
your duty to document them.
4.8 Avoid making your APIs overly clever
We observed earlier that the semantics of an API should be simple and
clear, and follow the principle of least surprise. If an API is too clever (e.g.,
if it has subtle side-effects), the users will not understand it as well and will
find themselves with subtle bugs in their applications. Cleverness also con-
tributes to making the code less readable and maintainable, and increases
the need for documentation.
Qt! QLabel in Qt 3 offers a beautiful example of cleverness. The setText()
method takes a string, which may be plain text or HTML. Qt automatically
detects the format by inspecting the string. This is sometimes a bit too clever
and occasionally results in the wrong format being chosen (which is a real
problem if the string comes from the end-user). On the other hand, the au-
tomatic detection usually works, is very convenient, and can be overridden
by calling setTextFormat(), so one could argue that this acceptable.
On the other hand, calling setText() with an HTML string in Qt 3 also
had the side-effect of setting the wordWrap property to true (the default be-
ing false). In turn, word-wrapping enables height-for-width, a layout fea-
ture that impacts the entire dialog. As a result, users who changed “Name”
to “<b>Name</b>” in one label found themselves with a totally different
dialog resizing behavior and couldn’t understand why.
4.9 Pay attention to edge cases
In the context of library programming, the importance of getting edge cases
right cannot be overstated. If you hear a colleague in the hallway say “It
doesn’t matter, it’s just a corner case”, please slap them in the face.
Edge cases are critical because they tend to ripple through an API. If
your fundamental string-search algorithm has bad edge-case semantics,
this might lead to bugs in the regular expression engine, which would lead
to bugs in applications that use regular expressions. But edge cases are also
important in their own right: Nobody is interested in a factorial function
that computes 0! = 0.
Qt! The Qt 3 static method QStringList::split(separator, string, allow-
EmptyEntries = false) split string at every occurrence of separator.
Thus, split(’:’, "a:b:c") returned the three-item list ["a", "b", "c"].
One could have expected that if separator occurs n times in string, the
28
29. resulting list would contain n + 1 items. However, split() managed to
violate this rule in two ways. First, the allowEmptyEntries parameter de-
faulted to false. Second, as a special case, the method always returned
the empty list if string was empty, rather than the one-item list [""]. Both
issues lead to subtle bugs in applications and bug reports to Trolltech.
In Qt 4, the method has been replaced by QString::split(separator,
behavior = KeepEmptyParts, caseSensitivity = Qt::CaseSensitive),
which doesn’t suffer from these flaws.
If the abstractions upon which you build handle edge cases gracefully,
your code is most likely to do so as well. To mismanage edge cases, you
often need extra code. Consider the following product() function:
double product(const QList<double> &factors)
{
// WRONG
if (factors.isEmpty())
return 0.0;
double result = 1.0;
for (int i = 0; i < factors.count(); ++i)
result *= factors[i];
return result;
}
If passed an empty list, the function returns 0, which is mathematically
unsound: The neutral element of multiplication is 1, not 0. We could of
course fix the check at the beginning of the function:
if (factors.isEmpty())
return 1.0;
But is this check necessary in the first place? It turns out it isn’t. The rest
of the function relies on C++’s for loop and multiplication operator, which
handle edge cases gracefully. The emptiness check is a false optimization—
it barely optimizes the trivial case, which is already blindingly fast, while
slowing down all other cases.
When implementing an API, start by handling the general case without
worrying about edge cases, and then test the edge cases. More often than
not, you will find that you don’t need any extra code for handling the edge
cases. (And when you do, it is usually a sign that one of the underlying
programming constructs is to blame.) Make sure, though, that the edge
cases are properly covered by unit tests, so that their semantics doesn’t
change between releases as a result of optimizations or other changes to
the code.
29
30. 4.10 Be careful when defining virtual APIs
Virtual APIs are notoriously difficult to get right and can easily break be-
tween releases. This is often called the “fragile base class problem”. When
designing a virtual API, there are two main mistakes to avoid.
The first mistake to define too few virtual methods. For library authors,
it is hard to foresee all the ways in which the library will be used. By omit-
ting the virtual keyword in front of a method declaration, we often reduce
the reusability and customizability of the entire class.
The second mistake is to make every method virtual. In a language like
C++, this is inefficient, but more importantly, it delivers a false promise.
More often than not, it would be useless, if not dangerous, to reimplement
some methods, because the class’s implementation doesn’t call them or ex-
pects them to have a specific semantics.
The proper approach requires thinking through what parts of the API
should be virtual and which parts should be non-virtual, and specifying
clearly in the documentation how the class uses the method itself.
Qt! The Spreadsheet example in the official Qt 3 book3 reimplemented QTable-
Item::text(), a virtual method. The example worked fine against Qt 3.2.0,
but was broken in a later Qt 3 release because some calls to text() in
QTable were replaced with direct access to the member variable that stores
the text in the default text() implementation, bypassing any subclass.
It usually pays off to cleanly separate a class’s public API, which is used
directly by applications, and the virtual API, which can be reimplemented
to customize the behavior of the class. In C++, this means making all virtual
methods protected.
Qt! In Qt 4, QIODevice successfully follows this approach. Direct users of the
class call read() and write(), while subclass authors reimplement read-
Data() and writeData(). In early implementations of QIODevice, the pub-
lic, non-virtual methods simply called the protected, virtual methods. Since
then, we added buffering, newline conversions, an “unget” buffer, and a
quick code path for reading one character at a time, all of this in the non-
virtual read() and write() methods.
In a way, QWidget follows this pattern as well with its event delivery
mechanism. Direct users of the class call show(), resize(), or repaint(),
whereas subclass authors reimplement showEvent(), resizeEvent(), or
paintEvent().
An annoying limitation of C++ is that we cannot add new virtual meth-
ods to an existing class without breaking binary compatibility. As an ugly
3Jasmin Blanchette and Mark Summerfield, C++ GUI Programming with Qt 3, Pren-
tice Hall, 2004. Available at http://www.informit.com/content/images/0131240722/
downloads/blanchette_book.pdf.
30
31. work around, get into the habit of providing a general virtual method that
can be used later on if you need to extend the class. For example:
virtual void virtual_hook(int id, void *data);
Structural
4.11 Strive for property-based APIs
Some APIs force users to specify all the attributes of an object upfront at
creation-time. Many low-level platform-specific APIs work this way. The
following example comes straight from a Win32 application:
m_hWindow =
::CreateWindow("AppWindow", /* class name */
m_pszTitle, /* title to window */
WS_OVERLAPPEDWINDOW, /* style */
CW_USEDEFAULT, /* start pos x */
CW_USEDEFAULT, /* start pos y */
m_nWidth, /* width */
m_nHeight, /* height */
NULL, /* parent HWND */
NULL, /* menu HANDLE */
hInstance, /* */
NULL); /* creatstruct param */
The need to display each argument on its own line and to accompany it
with a comment to increase readability is usually an indication that a pro-
cedure has too many parameters.
In contrast, a property-based approach lets users create an object with-
out specifying any arguments to the constructor. Instead, users can set the
properties that define the object one by one, in any order. For example:
window = new Window;
window->setClassName("AppWindow");
window->setWindowTitle(winTitle);
window->setStyle(Window::Overlapped);
window->setSize(width, height);
window->setModuleHandle(moduleHandle);
To the users, there are many advantages to this approach:
• It offers a very intuitive model.
31
32. • Users don’t need to remember in which order they need to supply
the attributes or options.
• User code is more readable and doesn’t require additional com-
ments (which may be out of sync with the code).
• Since properties have default values, users only have to set those
that they explicitly want to change (e.g., in the window example
above, they don’t have to set the x and y coordinates, the parent
window handle, the menu handle, or the “creatstruct”—whatever
that is).
• Users can change the value of a property at any time, instead of
having to replace the object with a new one whenever they want to
modify it.
• By calling getters, users can query back everything they set, which
helps debugging and is useful in some applications.
• The approach is compatible with graphical property editors, which
let the user see the result of setting a property immediately.
To the library developers, designing property-based APIs requires more
thinking. Since the properties can be set in any order, it is usually neces-
sary to use lazy initialization and other techniques in the implementation
to avoid recomputing the whole object every time a property changes.
Qt! Take QRegExp. Users can set it up in one go if they want:
QRegExp regExp("*.wk?", Qt::CaseInsensitive,
QRegExp::Wildcard);
But they can also initialize it step by step:
QRegExp regExp;
regExp.setPattern("*.wk?");
regExp.setCaseSensitivity(Qt::CaseInsensitive);
regExp.setPatternSyntax(QRegExp::Wildcard);
The QRegExp implementation delays the compilation the regular expression
or wildcard pattern to the point when the QRegExp object is actually used to
match some text.
4.12 The best API is no API
In a movie, the best special effects are those that you don’t notice. A similar
principle applies to API design: The ideal features are those that require no
(or very little) additional code from the application writer.
32
33. Qt! In Qt 3, widgets were restricted to 32 767 × 32 767 pixels on most platforms.
To render scenes larger than that in a QScrollView (e.g., large web pages),
the only solution was to subclass QScrollView and reimplement drawCon-
tents(), contentsMousePressEvents(), etc. Qt 4 works around the wid-
get size limitation internally for all QWidgets. As a result, we can now draw
large scenes in a QWidget’s paintEvent() the standard way and insert the
widget directly into a QScrollArea, eliminating the need for methods like
drawContents() and contentsMousePressEvents().
Other examples of significant Qt 4 features that have little API are PDF
support (which is enabled by calling setOutputFormat(QPrinter::Pdf-
Format) on a QPrinter), style sheets (which are set by calling setStyle-
Sheet()), and 2D painting using QPainter on an OpenGL widget (which
just works).
33